SpringBoot+Swagger导出HTML、MarkDown等离线文件

た入场券 2022-12-28 01:30 471阅读 0赞

前言:

1、两种方法：

1.1主要步骤：

1.2主要依赖：

2、实现

2.1 提示:

2.2使用代码方式导出

2.2使用插件方式导出

最后：

--------------------

# 前言: #

做后端开发，接口文档是必不可少的一部分，不论是前后端调试，还是给第三方调用，离线文档不可或少。现在swagger在线接口文档的流行，也依然少不了离线文档的编写，那这里就介绍怎么快速导出我们的swagger接口api并转换为我们想要的格式。

项目工具：idea

写在前面：springboot中配置swagger动态页面，可参考：[https://blog.csdn.net/qq\_40437152/article/details/108552258][https_blog.csdn.net_qq_40437152_article_details_108552258]

# 1、两种方法： #

1、通过代码的方式导出
    
    2、通过插件的方式导出

## 1.1主要步骤： ##

1> swagger2markup可以把swagger导出为markdown，asciidoc等格式
    
    2> asciidoctor-maven-plugin 可以把asciidoc导出为html、pdf等格式

## 1.2主要依赖： ##

**  解释：**这里主要用swagger2markup,下面的两个包是因为版本问题，因为我当时出现了：

java.lang.NoSuchMethodError: io.swagger.models.Response.responseSchema(Lio/swagger/models/Model;)Lio/swagger/models/Response;所以你可以直接按我的来！

<dependency>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup</artifactId>
                    <version>1.3.1</version>
                </dependency>
                
                <dependency>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-core</artifactId>
                    <version>1.5.16</version>
                </dependency>
                <dependency>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                    <version>1.6.0</version>
                </dependency>

# 2、实现 #

## 2.1 提示: ##

项目中swagger配置都有：例如一些标签 <Api>、<ApiOperation>

## 2.2使用代码方式导出 ##

**解释：**

webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT：代表使用配置的默认端口。

classes = Application.class：加载项目启动类，运行test方法不用启动项目。

swaggerUrl:读取的swagger配置文件，项目中没做配置的(加前缀什么的)，只需要修改自己对应的端口号就可以

接下来，只需要运行对应Test方法即可。

import io.github.swagger2markup.GroupBy;
    import io.github.swagger2markup.Language;
    import io.github.swagger2markup.Swagger2MarkupConfig;
    import io.github.swagger2markup.Swagger2MarkupConverter;
    import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
    import io.github.swagger2markup.markup.builder.MarkupLanguage;
    import org.junit.Test;
    import org.junit.runner.RunWith;
    import org.springframework.boot.test.context.SpringBootTest;
    import org.springframework.test.context.junit4.SpringRunner;
    
    import java.net.URL;
    import java.nio.file.Paths;
    
    @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT,classes = Application.class)//webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT
    @RunWith(SpringRunner.class)
    public class SwaggerExportTest {
    
        private final String swaggerUrl = "http://localhost:7749/v2/api-docs";
    
        /**
         * 生成AsciiDocs格式文档,并汇总成一个文件
         *
         * @throws Exception
         */
        @Test
        public void generateAsciiDocsToFile() throws Exception {
            //    输出Ascii到单文件
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
    
            Swagger2MarkupConverter.from(new URL(swaggerUrl))
                    .withConfig(config)
                    .build()
                    //project表示的是文件名,不用配置后缀
                    .toFile(Paths.get("src/docs/generated/ascii/project"));
        }
    
        /**
         * 生成Markdown格式文档,并汇总成一个文件
         *
         * @throws Exception
         */
        @Test
        public void generateMarkdownDocsToFile() throws Exception {
            //    输出Markdown到单文件
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
    
            Swagger2MarkupConverter.from(new URL(swaggerUrl))
                    .withConfig(config)
                    .build()
                     //project表示的是文件名,不用配置后缀
                    .toFile(Paths.get("src/docs/generated/markdown/project")); 
        }

## 2.2使用插件方式导出 ##

解释：把以下配置放到pom文件<bulid>下

1)启动我们的项目

2)点击插件swagger2markdown生成asciidioc

3)点击插件asciidoctor-maven-plugin生成对应的格式文件  asciidoctor:process-asciidoc

.![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNDM3MTUy_size_16_color_FFFFFF_t_70][]

<plugins>    
                
                <plugin>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup-maven-plugin</artifactId>
                    <version>1.3.1</version>
                    <configuration>
                        <swaggerInput>http://localhost:7749/v2/api-docs</swaggerInput>
                        
                        <outputFile>src/docs/generated/ascii/project</outputFile>
                        <config>
                            <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                            <swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
                            <swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
                            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        </config>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.6</version>
                    <configuration>
                        
                        <sourceDirectory>src/docs/generated/ascii</sourceDirectory>
                        
                        <outputDirectory>src/docs/generated/html</outputDirectory>
    
                        <headerFooter>true</headerFooter>
                        <doctype>book</doctype>
                        <backend>html5</backend>
                        <sourceHighlighter>coderay</sourceHighlighter>
                        <attributes>
                            
                            <toc>left</toc>
                            
                            <toclevels>3</toclevels>
                            
                            <sectnums>true</sectnums>
                        </attributes>
                    </configuration>
                </plugin>
            </plugins>

# 最后： #

项目中文件的生成路径是项目下的src文件夹，可自行修改；这里只做html格式的，其他的同上、只需要加对应的包、配置就好，有很多相关博客！

关于上面的版本问题，免了踩坑的问题。

参考博客:[https://blog.csdn.net/qq\_34727675/article/details/82961995][https_blog.csdn.net_qq_34727675_article_details_82961995]

欢迎留言！

[https_blog.csdn.net_qq_40437152_article_details_108552258]: https://blog.csdn.net/qq_40437152/article/details/108552258
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNDM3MTUy_size_16_color_FFFFFF_t_70]: /images/20221120/35790be1790144f1889e5743f8d4d6c0.png
[https_blog.csdn.net_qq_34727675_article_details_82961995]: https://blog.csdn.net/qq_34727675/article/details/82961995