Swagger离线接口文档生成总结
Swagger离线接口文档生成总结
前言
需求：项目使用spring boot，maven工程，需要使用swagger生成接口文档，格式为html。
在网上查了一些资料，大部分是使用swagger-ui，在线文档，不符合要求；小部分提到了离线文档生成，但是总觉得有点绕，结合实际的使用经验，输出总结一篇，供参考。
本文使用常见的生成流程，swagger json -> asciidoc -> html,下面说明使用过程的几个关键点。
关键点1： 生成swagger json
生成swagger json,需要曲线救国一下，要在单元测试中调用生成函数生成。
@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
//Application.class需要替换为你的工程中的applicaton类
//SwaggerConfig为swagger配置信息，详情如下
@SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
public class Swagger2MarkupTest {
@Autowired
private WebApplicationContext context;
private MockMvc mockMvc;
@Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();
}
@Test
public void convertSwaggerToAsciiDoc() throws Exception {
this.mockMvc.perform(get("/v2/api-docs")
.accept(MediaType.APPLICATION_JSON))
.andDo(Swagger2MarkupResultHandler
.outputDirectory("src/docs/asciidoc/generated").build())
.andExpect(status().isOk());
}
}
SwaggerConfig类主要配置需要扫描的接口信息，也放在单元测试的目录下。
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现
*
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//package包名替换为你的工程中需要扫描的接口的包名
.apis(RequestHandlerSelectors.basePackage("*.*.*.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XX在线接口文档")
.version("1.0")
.build();
}
}
这一步依赖的jar包如下：
io.swagger
swagger-annotations
1.5.19
io.springfox
springfox-swagger2
2.7.0
test
org.springframework.restdocs
spring-restdocs-mockmvc
1.1.2.RELEASE
test
完成上述这几步，运行测试，就会生成对应的swagger json文件。
关键点2:生成ascii doc
该步骤主要使用swagger2markup-maven-plugin来生成（gradle工程有对应的gradle plugin），pom配置如下：
io.github.swagger2markup
swagger2markup-maven-plugin
${swagger2markup.plugin.version}
io.github.swagger2markup
swagger2markup-import-files-ext
${swagger2markup.extension.version}
io.github.swagger2markup
swagger2markup
${swagger2markup.version}
${swagger.input}
${generated.asciidoc.directory}
ASCIIDOC
TAGS
${project.basedir}/src/docs/asciidoc/extensions/overview
${project.basedir}/src/docs/asciidoc/extensions/definitions
${project.basedir}/src/docs/asciidoc/extensions/paths
${project.basedir}src/docs/asciidoc/extensions/security
generate-sources
convertSwagger2markup
相关配置信息:
1.3.1
1.3.3
1.3.1
1.5.5
1.5.0-alpha.15
9.1.8.0
${project.basedir}/src/docs/asciidoc/generated/XXXX.json
${project.basedir}/src/docs/asciidoc
${project.build.directory}/asciidoc
${project.build.directory}/asciidoc/html
${project.build.directory}/asciidoc/pdf
关键点3：生成html或其它类型文件
该步骤使用assiidoc来将ascii doc文件转换为html或其它类型文件。
org.asciidoctor
asciidoctor-maven-plugin
1.5.5
org.asciidoctor
asciidoctorj-pdf
${asciidoctorj.pdf.version}
org.jruby
jruby-complete
${jruby.version}
org.asciidoctor
asciidoctorj
${asciidoctorj.version}
${asciidoctor.input.directory}
index.adoc
book
left
3
${generated.asciidoc.directory}
output-html
generate-resources
process-asciidoc
html5
${asciidoctor.html.output.directory}
output-pdf
generate-resources
process-asciidoc
pdf
${asciidoctor.pdf.output.directory}
index.adoc的内容:
include::{generated}/overview.adoc[]
include::{generated}/security.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]
ok,完成这三个步骤，运行mnv install命令，就可以生成出像样的接口文档了。
总结
在实际使用中，可以将文件转换的工作当做一个单独的工程，swager json文件生成只作为单元测试代码存在，这样整个工程真正需要打进jar包的只有swagger-annotations，对现有代码影响较小，功能也很独立。
参考文档:
[1] 从代码中生成接口文档的完整过程–Gradle工程实例
[2] 将Swagger文件转换为html文件的maven工程示例
[3] Swagger2Markup官方文档
[4] Swagger2离线文档：PDF和Html5格式
[6] Swagger+spring boot 转换为html,PDF文件等