背景
- 服务端开发同学需要花很多时间编写和维护大量的Rest接口文档，且往往接口修改后没有及时同步文档，让对接方和后续维护者一头雾水。
- 有没有一种方式可以相对容易地生成可读性好的Rest文档，并且做到与代码同步？
目标
- 通过Swagger注释自动生成Rest文档接口。
- 通过Swagger2Markup生成静态文档（html/markdown/wiki）
使用Swagger注解自动生成Rest文档接口
maven引入Swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
配置Swagger
@SpringBootApplication
@EnableSwagger2
public class AppStarter extends WebMvcConfigurerAdapter {
public static void main(String[] args) {
SpringApplication.run(AppStarter.class, args);
}
/**
* 创建Rest Api描述
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() //按条件指定生成文档接口
.paths(PathSelectors.any())
.build();
}
/**
* 接口描述
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试项目")
.description("User实体CRUD")
.version("1.0")
.build();
}
}
- EnableSwagger2启动Swagger
- 创建Docket
使用Swagger注解
controller注解
@RestController
@RequestMapping("/v1/users")
@Api(description = "用户管理接口")
public class UserController {
@PostMapping
@ApiOperation("创建用户")
public void addUser(@RequestBody User user){
}
@GetMapping
@ApiOperation("查询用户")
public List<User> getUsers(@ApiParam(value = "模糊查询用户名") String name){
return Lists.newArrayList(
User.builder().id(1).name("test-name1").birth(new Date()).build(),
User.builder().id(2).name("test-name2").birth(new Date()).build()
);
}
@GetMapping("/{id}")
@ApiOperation("获取用户")
public User getUser(@ApiParam(value = "用户ID") @PathVariable long id){
return User.builder().id(id).name("test-name").birth(new Date()).build();
}
@PutMapping("/{id}")
@ApiOperation("修改用户")
public void updateUser(@ApiParam(value = "用户ID") @PathVariable long id,
@RequestBody User user){
}
@DeleteMapping("/{id}")
@ApiOperation("删除用户")
public void deleteUser(@ApiParam(value = "用户ID") @PathVariable long id){
}
}
| 注解 | 作用域 | 说明 |
|---|---|---|
| Api | controller类名 | 描述controller |
| ApiOperate | controller方法 | 描述接口方法 |
| ApiParam | path或param参数 | 描述接口参数 |
实体注解
@ApiModel("用户")
public class User {
@ApiModelProperty("用户ID")
private long id;
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("生日")
private Date birth;
}
| 注解 | 作用域 | 说明 |
|---|---|---|
| ApiModel | 实体类名 | 描述实体 |
| ApiModelProperty | 实体属性 | 描述属性 |
生成api-docs
- 打好注解后，编译，启动项目。
- swagger会在springmvc中创建 GET http://host:port/v2/api-docs 接口，输出json格式的rest api文档
使用Swagger2Markup生成静态文档
- 有了swagger的文档api，需要将其生成可读的文本文档（html/markdown/wiki），并静态化。
启动项目
- 将写好注解的项目启动，并保证/v2/api-docs接口可以访问。
配置swagger2markup插件
- maven.build.plugins增加swagger2markup插件
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
<!-- api-docs访问url -->
<swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
<!-- 生成为单个文档，输出路径 -->
<outputFile>src/docs/asciidoc/generated/all</outputFile>
<!-- 生成为多个文档，输出路径 -->
<!--<outputDir>src/docs/asciidoc/generated</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>
运行swagger2markup插件
- mvn命令运行swagger2markup:convertSwagger2markup
- 在项目的/src/docs/asciidoc/generated中找到结果文件
处理结果文件
CONFLUENCE_MARKUP（wiki）
- confluence的wiki支持此格式
-
使用插入”wiki标记“
-
选择“企业维基”，将内容复制进去
MARKDOWN
- 可用在任何支持markdown的编辑器中
ASCIIDOC（html）
- ascii文档，可以再进一步将其转换为可读性优秀的html文档
配置asciidoctor插件
- maven.build.plugins中增加配置
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<!-- asciidoc文档输入路径 -->
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<!-- html文档输出路径 -->
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<!-- html文档格式参数 -->
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
</attributes>
</configuration>
</plugin>