SpringBoot接口文档自动生成最佳方案

背景

最近研发团队需要做有状态服务，需要复杂的yaml格式的数据抽象为对象，接⼝定义⼊参出参涉及的字段多，对象多，接⼝⽂档编写将是个⿇烦事，尤其是前后端分离的开发模式下，维护好接⼝⽂档尤其重要。

⼿动维护接⼝⽂档，费时费⼒，⽽且接⼝可能改，前端拿到的⽂档可能已过期，可能造成许多不必要的⿇烦，你可以想象你的前端同事想杀死你的表情，因此⾃动⽣成接⼝⽂档的⽅案尤为重要。

以下是⼏种⽅案选型，⽂章结尾给出了我个⼈认为的最佳实践。

Swagger-UI

官⽹链接地址：GitHub：

直接运⾏，可以在线测试 API 接⼝。号称世界上最流⾏的 API 框架。

RESTFul API ⽂档在线⾃动⽣成⼯具 API ⽂档与 API 定义同步更新。⽀持多种语⾔ 如：Java 、PHP、Asp.net……

简介

Swagger UI 允许任何⼈（⽆论您是开发团队还是最终⽤户）都可以可视化 API 资源并与之交互，⽽⽆需任何实现逻辑。它是根据您的 OpenAPI（以前称为 Swagger）规范⾃动⽣成的，具有可视化⽂档，可简化后端实现和客户端使⽤。

特点

⽆依赖 UI 可以在任何开发环境中使⽤，⽆论是本地还是在 Web 端中。

⼈性化 允许最终开发⼈员轻松地进⾏交互，并尝试 API 公开的每个操作，以⽅便使⽤。易于浏览 归类整齐的⽂档可快速查找并使⽤资源和端点。

所有浏览器⽀持 Swagger UI 在所有主要浏览器中均可使⽤，以适应各种可能的情况。完全可定制 通过完整的源代码访问⽅式以所需⽅式设置和调整 Swagger UI。完整的 OAS ⽀持 可视化 Swagger 2.0 或 OAS 3.0 中定义的 API。

SpringBoot 集成 Swagger

POM ⽂件中导⼊ springfox-swagger2 和 springfox-swagger-ui

io.springfox

springfox-swagger2 2.7.0

io.springfox

springfox-swagger-ui 2.7.0

配置 Swagger 编写 SwaggerConfig ⽂件,具体配置如下

@Configuration

public class SwaggerConfig { @Bean

public Docket customDocket() {

ParameterBuilder tokenPar = new ParameterBuilder(); List pars = new ArrayList(); tokenPar.name(\"token\").description(\"user token\") .modelRef(new ModelRef(\"string\")) .parameterType(\"header\") .required(false).build(); pars.add(tokenPar.build());

return new Docket(DocumentationType.SWAGGER_2) .select()

.apis(RequestHandlerSelectors.any()) .build()

.globalOperationParameters(pars) .apiInfo(apiInfo())

.securitySchemes(securitySchemes()) .securityContexts(securityContexts()); }

ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title(\"api swagger document\") .description(\"swagger api\") .build(); }

private List securitySchemes() { List apiKeys = new ArrayList<>();

apiKeys.add(new ApiKey(\"Authorization\ return apiKeys; }

private List securityContexts() {

List securityContexts = new ArrayList<>(); securityContexts.add(SecurityContext.builder() .securityReferences(defaultAuth())

.forPaths(PathSelectors.regex(\"^(?!auth).*$\")).build()); return securityContexts; }

private List defaultAuth() {

AuthorizationScope authorizationScope = new AuthorizationScope(\"global\ AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope;

List securityReferences = new ArrayList<>();

securityReferences.add(new SecurityReference(\"Authorization\ return securityReferences; }}

启动类加注解@EnableSwagger2 开启 Swagger2@ApiParam @ApiModelProperty

总结

Swagger UI有两种风格，每个⼈使⽤习惯不同，根据具体喜好选择⾃⼰中意的风格。

Yapi

简介

YApi 是⾼效、易⽤、功能强⼤的 api 管理平台，旨在为开发、产品、测试⼈员提供更优雅的接⼝管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为⽤户提供了优秀的交互体验，开发⼈员只需利⽤平台提供的接⼝数据写⼊⼯具以及简单的点击操作就可以实现接⼝的管理。

特点

基于 Json5 和 Mockjs 定义接⼝返回数据的结构和⽂档，效率提升多倍扁平化权限设计，即保证了⼤型企业级项⽬的管理，⼜保证了易⽤性类似 postman 的接⼝调试

⾃动化测试, ⽀持对 Response 断⾔

MockServer 除⽀持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据⽀持 postman, har, swagger 数据导⼊

免费开源，内⽹部署，信息再也不怕泄露了

教程

代码增量实现

通过⾃动识别 Swagger 地址解析成 Yapi 可识别的⼊参或者出参

当前问题

返回的数据是 AjaxResult 继承了 HashMap，swagger ⽆法识别每个字段的含义？yapi 可识别的数据格式是什么？解决

定义了返回类型 Result

@Component@Data

public class Result implements Serializable {

private static final long serialVersionUID = -6322750099185092004L; @ApiModelProperty(name = \"status\状态：y,n\") private String status;

@ApiModelProperty(name = \"success\是否成功\") private boolean success;

@ApiModelProperty(name = \"msg\提⽰信息\") private String msg;

@ApiModelProperty(name = \"info\错误信息\") private String info;

@ApiModelProperty(name = \"data\返回对象\") private T data;

private static final String STATUS_Y = \"y\"; private static final String STATUS_N = \"n\"; public Result() { }

public Result(boolean success, String msg, T data) { this.success = success; this.msg = msg; this.data = data; }

public Result(boolean success, String status) { this.success = success; this.status = status; }

public Result(boolean success, String msg, String status, String info) { this.success = success; this.msg = msg; this.status = status; this.info = info; }

public static Result success(String msg) { return new Result(true, msg, STATUS_Y, msg); }

public static Result success() { return new Result(true, STATUS_Y); }

public static Result success(T data) { return new Result(true, \"\ }

public static Result error(String error) {

return new Result(false, error, STATUS_N, error); }}

JSON-SCHEMA

JSON Schema

定义

JSON 是⽬前应⽤⾮常⼴泛的数据交换格式。既然是⽤于数据交换的格式，那么就存在数据交换的双⽅。如何约定或校验对⽅的数据格式是符合要求的，就成了服务交互需要解决的⼀个问题。所以 JSON Schema 就是⽤来定义 JSON 数据约束的⼀个标准。根据这个约定模式，交换数据的双⽅可以理解 JSON 数据的要求和约束，也可以据此对数据进⾏验证，保证数据交换的正确性。版本

The current version is 2019-09!格式

{

\" $schema\" : \"http://json-schema.org/draft-07/schema#\ \"$ id\" : \"http://example.com/product.schema.json\ \"description\" : \"A product from Acme's catalog\ \"properties\" : { \"dimensions\" : { \"properties\" : { \"height\" : {

\"type\" : \"number\"

},

\"length\" : {

\"type\" : \"number\" },

\"width\" : {

\"type\" : \"number\" } },

\"required\" : [ \"length\ \"type\" : \"object\" },

\"price\" : {

\"description\" : \"The price of the product\ \"exclusiveMinimum\" : 0, \"type\" : \"number\" },

\"productId\" : {

\"description\" : \"The unique identifier for a product\ \"type\" : \"integer\" },

\"productName\" : {

\"description\" : \"Name of the product\ \"type\" : \"string\" },

\"tags\" : {

\"description\" : \"Tags for the product\ \"items\" : {

\"type\" : \"string\" },

\"minItems\" : 1, \"type\" : \"array\ \"uniqueItems\" : true } },

\"required\" : [ \"productId\ \"title\" : \"Product\ \"type\" : \"object\"}

分析说明：\" $schema\": \"\"

说明当前使⽤的schema版本，可以不包含\"$ id\": \"\"

当前 schema 的唯⼀ id 标识，⼀般指向⼀个⾃主域名。⽅便后续引⽤，可以不包含\"title\": \"Product\"

当前 schema 的标题，简要描述信息，可不包含\"description\": \"A product from Acme's catalog\"详细描述信息，可不包含\"type\": \"object\"

约束对象是 object，也就是在 { } 中的数据\"properties\": {\"productId\": {

\"description\": \"The unique identifier for a product\\"type\": \"integer\"}

object 中具体属性的约束，description 是描述信息，不产⽣具体约束。type 约束 productid 属性类型为整型\"productName\": {

\"description\": \"Name of the product\\"type\": \"string\"},

约束 productName 属性类型为字符型\"price\": {

\"description\": \"The price of the product\\"type\": \"number\

\"exclusiveMinimum\": 0}

约束 price 属性类型为数字型，可以是整型或浮点型。exclusiveMinimum 约束该数字 >0（不包含 0）\"tags\": {

\"description\": \"Tags for the product\\"type\": \"array\\"items\": {

\"type\": \"string\"},

\"minItems\": 1,

\"uniqueItems\": true}

约束 tag 属性是 array 数组。items 是数组项约束，这⾥约束数组项均为字符型minItems 数组⾄少包含 1 项。uniqueItems 约束数组中每项不得重复

{

\"dimensions\" : { \"properties\" : { \"height\" : {

\"type\" : \"number\" },

\"length\" : {

\"type\" : \"number\" },

\"width\" : {

\"type\" : \"number\" } },

\"required\" : [ \"length\ \"type\" : \"object\"}}

约束 dimensions 嵌套对象，其中 length，width，height 均为数字类型且这三个字段在 dimensions 对象中必须包含

{

\"required\" : [ \"productId\}

当前数据对象必须包含 productId，productName，price 三个字段

个⼈总结

Swagger bootstrap ui

swagger-ui需要配置的地⽅这⾥也要swagger-bootstrap-ui官⽹：Spring Boot导⼊POM依赖

io.springfox

springfox-swagger2 2.9.2

com.github.xiaoymin swagger-bootstrap-ui 1.9.2

访问

总结

项⽬中采⽤swagger-ui作为⾃动⽣成⽂档⼯具⾮常⽅便，⽆需花费额外的时候维护接⼝⽂档，⽽swagger-bootstrap-ui更强⼤，可以在线⽣成.md格式接⼝⽂档，除了开发⼈员⾃⼰使⽤外，导出作为项⽬交付物也⾮常⽅便，个⼈建议Spring Boot项⽬中使⽤swagger-bootstrap-ui作为接⼝⽂档⼯具是最佳⽅案，本⼈所在项⽬⾃从使⽤了该插件后，再没⽤过其他类似⼯具，得到团队⼀致肯定，测试也经常采⽤该⼯具测试接⼝。总之⼀句话，选择swagger-bootstrap-ui就对了，你会爱上它的。