生成Swagger2静态文档

最新推荐文章于 2024-05-23 10:15:34 发布

「已注销」

最新推荐文章于 2024-05-23 10:15:34 发布

阅读量4.5k

点赞数 3

原文：https://blog.csdn.net/qq_34727675/article/details/82961995
SpringBoot将Swagger2导出静态文档
swagger文档每次都需要开启项目才能使用。不方便传阅。目前通过swagger2markup可以将swagger导出为markdown，asciidoc等。

swagger2markup
这个项目是在github上的 https://github.com/Swagger2Markup/swagger2markup
有两种生成静态文档的方式
1.通过运行test方式生成
2.通过maven插件方式生成

asciidoctor-maven-plugin
https://asciidoctor.org/docs/asciidoctor-maven-plugin/
https://github.com/asciidoctor/asciidoctor-maven-examples
asciidoctor-maven-plugin 插件可以吧 asciidoc转成html等

步骤
通过test生成静态文档
1.导入对应的jar包
2.编写对应的生成方法
3.运行生成对应的文档
通过maven插件生成
1.导入对应的插件
2.运行maven命令
一、通过test生成静态文档
先导入对应的jar包

<!--swagger2-->

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.0</version>
        </dependency>
        <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.5.16</version>
        </dependency>

前两个是我springboot接入swagger2的jar包，正常是只需要swagger2markup这个包，后面两个也是不需要的，全部放出来特意说明一下因为jar包原因有可能导致的问题

java.lang.NoSuchMethodError: io.swagger.models.Response.responseSchema(Lio/swagger/models/Model;)Lio/swagger/models/Response;
java.lang.NoSuchFieldError: MULTIPLE_OF
因为 springfox-swagger2 --2.60这个版本里面对应的swagger-core是1.5.12 ，swagger-models是1.5.10的。想要通过swagger2markup生成静态文档需要通过core和model转换成对应的实体格式。然而core和model好像11前都没有向后兼容，所以需要core和model都需要在1.5.11之上。我后面引入的 core和model就是为了替换springfox-swagger2里面的包，问题参考于
https://github.com/Swagger2Markup/swagger2markup/issues/273

在这里插入图片描述
https://github.com/Swagger2Markup/swagger2markup/issues/234

pom中还要添加一下远程仓库（要不要都无所谓）

 <repositories>
        <repository>
            <id>jcentral</id>
            <name>bintray</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

下面开始编写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;

@RunWith(SpringRunner.class)
//设定端口，申明启动类！！重要
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT, classes = WeatherApplication.class)
public class GenerateMarkDownApi {
    /**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//设置生成格式
                .withOutputLanguage(Language.ZH)//设置语言中文还是其他语言
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        //设置swagger-api的json来源
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));//设置生成文件的路径
    }

    /**
     * 生成Markdown格式文档
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    }
    /**
     * 生成Confluence格式文档
     * @throws Exception
     */
    @Test
    public void generateConfluenceDocs() throws Exception {
        //    输出Confluence使用的格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/confluence/generated"));
    }

    /**
     * 生成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("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

    /**
     * 生成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("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
    }
}

@SpringBootTest 里面的class需要修改成自己的启动类

MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP
from(new URL(“http://localhost:8080/v2/api-docs”)：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
toFolder(Paths.get("./docs/asciidoc/generated")：指定最终生成文件的具体目录位置
运行其中一个@Test即可

我是运行生成合成一个asciidoc文件的以及markdown

二、通过maven插件生成
添加对应的插件

  <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput><!---swagger-api-json路径-->
                    <outputDir>src/docs/asciidoc/generated</outputDir><!---生成路径-->
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式-->
                    </config>
                </configuration>
            </plugin>

详细的配置设置在github上大家可以去看看
https://github.com/Swagger2Markup/swagger2markup-maven-plugin

把项目运行起来，再运行插件就好了

通过插件吧 asciidoc转成html

org.asciidoctor asciidoctor-maven-plugin 1.5.6 docs/asciidoc/generated docs/asciidoc/html html coderay left true

详细的设置配置参考
https://asciidoctor.org/docs/asciidoctor-maven-plugin/

单击或者输入mvn命令 asciidoctor:process-asciidoc
在这里插入图片描述

最终生成html文件用浏览器打开
在这里插入图片描述

效果图
在这里插入图片描述

「已注销」

关注

3
点赞
踩
8

收藏

觉得还不错? 一键收藏
0
评论
生成Swagger2静态文档

生成Swagger2静态文档 swagger文档每次都需要开启项目才能使用。不方便传阅。目前通过swagger2markup可以将swagger导出为markdown，asciidoc等。swagger2markup这个项目是在github上的 https://github.com/Swagger2Mark...
复制链接

扫一扫