Swagger离线接口文档生成总结
前言
需求:项目使用spring boot,maven工程,需要使用swagger生成接口文档,格式为html。
在网上查了一些资料,大部分是使用swagger-ui,在线文档,不符合要求;小部分提到了离线文档生成,但是总觉得有点绕,结合实际的使用经验,输出总结一篇,供参考。
本文使用常见的生成流程,swagger json -> asciidoc -> html,下面说明使用过程的几个关键点。
关键点1: 生成swagger json
生成swagger json,需要曲线救国一下,要在单元测试中调用生成函数生成。
@WebAppConfiguration
@RunWith()
//需要替换为你的工程中的applicaton类
//SwaggerConfig为swagger配置信息,详情如下
@SpringApplicationConfiguration(classes = {, })
public class Swagger2MarkupTest {
@Autowired
private WebApplicationContext context;
private MockMvc mockMvc;
@Before
public void setUp() {
= ().build();
}
@Test
public void convertSwaggerToAsciiDoc() throws Exception {
(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(("*.*.*.controller"))
.paths(())
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XX在线接口文档")
.version("1.0")
.build();
}
}
这一步依赖的jar包如下:
<!--主要用于函数和类的解释说明,swagger会扫描注解,生成对应信息-->
<!--如果不需要更多说明,该jar包可以移除-->
<dependency>
<groupId></groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.19</version>
</dependency>
<dependency>
<groupId></groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId></groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<version>1.1.</version>
<scope>test</scope>
</dependency>
完成上述这几步,运行测试,就会生成对应的swagger json文件。
关键点2:生成ascii doc
该步骤主要使用swagger2markup-maven-plugin来生成(gradle工程有对应的gradle plugin),pom配置如下:
<plugin>
<groupId>.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>${}</version>
<dependencies>
<dependency>
<groupId>.swagger2markup</groupId>
<artifactId>swagger2markup-import-files-ext</artifactId>
<version>${}</version>
</dependency>
<dependency>
<groupId>.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>${}</version>
</dependency>
</dependencies>
<configuration>
<!--swagger json路径-->
<swaggerInput>${}</swaggerInput>
<!--ascii doc输出目录-->
<outputDir>${}</outputDir>
<config>
<>ASCIIDOC</>
<>TAGS</>
<>${}/src/docs/asciidoc/extensions/overview</>
<>${}/src/docs/asciidoc/extensions/definitions</>
<>${}/src/docs/asciidoc/extensions/paths</>
<>${}src/docs/asciidoc/extensions/security</>
</config>
</configuration>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>convertSwagger2markup</goal>
</goals>
</execution>
</executions>
</plugin>
相关配置信息:
<properties>
<>1.3.1</>
<>1.3.3</>
<>1.3.1</>
<>1.5.5</>
<>1.5.0-alpha.15</>
<>9.1.8.0</>
<!--swagger json路径,在convertSwaggerToAsciiDoc中指定,替换成自己工程中的路径-->
<>${}/src/docs/asciidoc/generated/</>
<!--assiidoc使用的输入目录,adoc文件所在路径-->
<>${}/src/docs/asciidoc</>
<!--assiidoc输出目录-->
<>${}/asciidoc</>
<!--html文件输出目录-->
<>${}/asciidoc/html</>
<!--pdf文件输出目录-->
<>${}/asciidoc/pdf</>
</properties>
关键点3:生成html或其它类型文件
该步骤使用assiidoc来将ascii doc文件转换为html或其它类型文件。
<plugin>
<groupId></groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.5</version>
<dependencies>
<!-- 生成pdf文件的jar包依赖。(如果不需要可以移除) -->
<dependency>
<groupId></groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${}</version>
</dependency>
<!-- Comment this section to use the default jruby artifact provided by the plugin -->
<dependency>
<groupId></groupId>
<artifactId>jruby-complete</artifactId>
<version>${}</version>
</dependency>
<!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
<dependency>
<groupId></groupId>
<artifactId>asciidoctorj</artifactId>
<version>${}</version>
</dependency>
</dependencies>
<configuration>
<!-- asciidoc输入目录,该目录用于存放adoc文件,我的理解是生成文档的框架文件,用于描述文档结构的-->
<sourceDirectory>${}</sourceDirectory>
<!--指定adoc文件名-->
<sourceDocumentName></sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<!--ascii doc文件所在路径,步骤2中的输出目录-->
<generated>${}</generated>
</attributes>
</configuration>
<executions>
<!-- 生成html文件 -->
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<!--html输出目录-->
<outputDirectory>${}</outputDirectory>
</configuration>
</execution>
<!-- 生成pdf文件.(如果不需要可以移除) -->
<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<!-- pdf文件输出目录-->
<outputDirectory>${}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
的内容:
include::{generated}/[]
include::{generated}/[]
include::{generated}/[]
include::{generated}/[]
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文件等