swagger注释HTML,Swagger注解生成Rest Api文档

背景

服务端开发同学需要花很多时间编写和维护大量的Rest接口文档，且往往接口修改后没有及时同步文档，让对接方和后续维护者一头雾水。

有没有一种方式可以相对容易地生成可读性好的Rest文档，并且做到与代码同步？

目标

通过Swagger注释自动生成Rest文档接口。

通过Swagger2Markup生成静态文档(html/markdown/wiki)

使用Swagger注解自动生成Rest文档接口

maven引入Swagger依赖

io.springfox

springfox-swagger2

2.7.0

配置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 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插件

io.github.swagger2markup

swagger2markup-maven-plugin

1.3.1

http://localhost:8080/v2/api-docs

src/docs/asciidoc/generated/all

CONFLUENCE_MARKUP

TAGS

运行swagger2markup插件

image.png

mvn命令运行swagger2markup:convertSwagger2markup

在项目的/src/docs/asciidoc/generated中找到结果文件

处理结果文件

CONFLUENCE_MARKUP(wiki)

confluence的wiki支持此格式

使用插入”wiki标记“

image.png

选择“企业维基”，将内容复制进去

image.png

MARKDOWN

可用在任何支持markdown的编辑器中

ASCIIDOC(html)

ascii文档，可以再进一步将其转换为可读性优秀的html文档

配置asciidoctor插件

maven.build.plugins中增加配置

org.asciidoctor

asciidoctor-maven-plugin

1.5.6

src/docs/asciidoc/generated

src/docs/asciidoc/html

html

coderay

book

left

3

运行asciidoctor插件

image.png

参考资料