场景
有时候需要为前端开发者提供Restful Api说明文档，通过word文档创建和修改非常耗时，希望有一种比较便捷的第三方库可以减少生成Api说明文档的工作量
基于Spring的Restful Api生成工具
术语解析
- Springfox-swagger2
Swagger是一个可以生成基于多种语言编写的Restful Api的文档生成工具，详见这里。
查看Springfox-swagger2注解文档，请点击这里 - Swagger2markup
Swagger2markup是一个使用java编写的将Swagger语义转换成markdown、asciidoc文本格式的开源项目
Swagger2Markerup的详细说明请见这里 - Asciidoc
AsciiDoc是一种MarkDown的扩展文本格式，AsciiDoc相比MarkDown更适合编写类似API文档，学术文档这样的文档。
详见这里 - Asciidoctor
asciidoctor是一个由ruby编写的可以将 asciidoc转换成html、pdf的开源项目，这个项目有java版本和maven插件，详见这里
接口生成原理
- generate an up-to-date Swagger JSON file during an unit or integration test
使用Springfox-swagger2生成swagger json文件 - convert the Swagger JSON file into AsciiDoc
使用Swagger2markup将swagger json文件转换成asciidoc文档片段 - add hand-written AsciiDoc documentation
编写asciidoc的文档(主要是组装步骤2中生成的asciidoc文档片段) - convert AsciiDoc into HTML and PDF
使用Asciidoctor将asciidoc转换成HTML 或pdf
Swagger部署说明
- 在pom引入下面依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
<scope>test</scope>
</dependency>
- 配置一个SwaggerConfig
@EnableSwagger2
@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
@Bean
public Docket restApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.securitySchemes(asList(
new OAuth(
"petstore_auth",
asList(new AuthorizationScope("write_pets", "modify pets in your account"),
new AuthorizationScope("read_pets", "read your pets")),
Arrays.<GrantType>asList(new ImplicitGrant(new LoginEndpoint("http://petstore.swagger.io/api/oauth/dialog"), "tokenName"))
),
new ApiKey("api_key", "api_key", "header")
))
.select()
.paths(Predicates.and(ant("/**"), Predicates.not(ant("/error")), Predicates.not(ant("/management/**")), Predicates.not(ant("/management*"))))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger Petstore")
.description("Petstore API Description")
.contact(new Contact("TestName", "http:/test-url.com", "test@test.de"))
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.version("1.0.0")
.build();
}
}
- 运行Spring项目
运行项目后会发布Spring的路由器多了若干个对外的接口，其中一个是/v2/api-docs/。
通过这个接口可以获取到由Swagger生成的所有API接口的元数据。 - Api界面部署
呈现由Swagger生成的API大概有两种方法（目前只找到两种）
- Swagger自带有Swagger-UI可以直观显示API接口说明并可以在线调试
- 使用Swagger2Markerup插件和AsciiDoc插件可以将Swagger生成的JSON元数据转换成HTML、PDF
注意：springfox-swagger2是依赖与Spring MVC框架的！！
Swagger-UI部署
- 引入Swagger-UI依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
- 运行Spring项目，并访问htttp://[host]:[ip]/swagger-ui.html
截图.png
其它的插入位置同理
swagger2markup-spring-restdocs-ext
插件说明
此插件可以自动将Spring rest doc生成的adoc片段添加到Paths说明部分的最后。
Spring Rest doc生成的adoc版片段：
- curl-request.adoc
- http-request.adoc
- http-response.adoc
- httpie-request.adoc
插件默认扫描前3个adoc，当然也可以通过withExplicitSnippets自定义扫描的文件名。
插件使用
- maven插件部署
这里我们使用与上一个述件不同的部署方式，直接到通过代码配置插件
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
- 配置
Map<String, String> configMap = new HashMap<>();
configMap.put("swagger2markup.extensions.springRestDocs.snippetBaseUri", "docs/restful/snippets");
configMap.put("swagger2markup.extensions.springRestDocs.defaultSnippets", "true");
configMap.put(Swagger2MarkupProperties.PATHS_GROUPED_BY, GroupBy.TAGS.name());
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder(configMap)
其中snippetBaseUri是Spring Rest Doc生成文档的位置；defaultSnippets指明是否使用默认的文件名扫描，如果设置为false，需要手工创建插件并通过withExplicitSnippets自行设置扫描的文件名。
其他参考资料
Spring Boot Test
http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-testing.html
网友评论