生成Swagger2静态文档
原文：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包
io.springfox
springfox-swagger2
2.6.0
io.springfox
springfox-swagger-ui
2.6.0
io.github.swagger2markup
swagger2markup
1.3.1
io.swagger
swagger-core
1.5.16
io.swagger
swagger-models
1.5.16
前两个是我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中还要添加一下远程仓库 （要不要都无所谓）
jcentral
bintray
http://jcenter.bintray.com
false
下面开始编写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插件生成
添加对应的插件
io.github.swagger2markup
swagger2markup-maven-plugin
1.3.1
http://localhost:8080/v2/api-docs
src/docs/asciidoc/generated
ASCIIDOC
详细的配置设置在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文件用浏览器打开
效果图
