2,接口导出
访问项目:/v2/api-docs ,确认有接口的json格式数据返回;
2.1 利用swagger2markup导出接口
2.1.1 依赖
maven插件的方式
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
<!-- api-docs访问url -->
<swaggerInput>http://localhost:8080/product/v2/api-docs</swaggerInput>
<!-- 生成为单个文档,输出路径
<outputFile>src/main/doc/api</outputFile>-->
<!-- 生成为多个文档,输出路径 -->
<outputDir>src/main/doc/apiall</outputDir>
<config>
<!-- wiki格式文档 -->
<!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage> -->
<!-- ascii格式文档 -->
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<!-- markdown格式文档 -->
<!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
</config>
</configuration>
</plugin>
2.1.2 依赖插件参数说明:
configuration.swaggerInput :该标签内容需修改为需要导出接口项目的/v2/api-docs 路径
configuration.outputFile :该标签为生成单个文档指定文档生成路径,如生成txt、md等文件,可随意修改;但注意,该标签与outputDir标签二选一;
configuration.outputDir :该标签为生成多个文档指定文档目录,如生成ASCIIDOC文件,该类文件可用于结合asciidoctor插件生成html文件;
configuration.config :该标签内定义的swagger2markup.markupLanguage子标签,只能同时存在一个,如指定生成markdown 即md文件时,就不能指定生成其他类型;
注意:指定生成ASCIIDOC文件类型时,需与configuration.outputDir标签配合使用;
2.1.2 使用:
运行当前项目
确认系统的 /v2/api-docs 接口可用
进入项目根目录,进入cmd ,执行mvn命令:mvn swagger2markup:convertSwagger2markup
结果确认:将在configuration.outputDir 或configuration.outputFile标签指定的目录和文件,生成对应的接口文档;
2.2.1 使用asciidoctor配合swagger2markup生成html文件
2.2.2 依赖
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/main/doc/apiall</sourceDirectory>
<outputDirectory>src/main/doc/api/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>
</plugin>
2.2.3 依赖配置说明:
configuration.sourceDirectory :该标签用于指定利用ASSIIDOC文件生成html的资源目录,即该标签需要与swagger2markup生成的ASSIIDOC文件在同一个目录,一般讲该标签目录设置与swagger2markup插件configuration.outputDir标签内容一致即可;
2.2.4 使用
在利用swagger2markup生成了ASSIIDOC文件之后,将configuration.sourceDirectory 指定到ASSIIDOC文件的目录
进入到项目根路径,使用maven命令:mvn asciidoctor:process-asciidoc
————————————————