swagger接口文档同步yapi定义标准_swagger接口文档自动同步yapi

---

title: swagger接口文档同步yapi定义标准
date: 2021-08-07 13:18:29
tags:

• 接口文档
• swagger
• yapi
  categories:
• [接口文档,swagger,yapi]

---

前提

在与前端约定yapi接口后，后端可能会与前端私下沟通修改接口方案或者业务调整未同步至yapi,导致经常性会出现实际开发接口与yapi维护的接口不统一的情况。滞后的接口文档，给后续介入开发的人员会造成很大的困惑，这也是这块未统一规范的体现。所以文章旨在通过一种定义标准（选型：swagger），通过实际开发中的代码生成yapi接口文档。一般情况下，联调接口会先于开发定义出来，所以需要定义两套文档，一套用于与前端或业务系统联调，另一套生成用于业务系统实际的开发接口。

swagger使用

配置swagger

以Swagger2为例，添加jar包

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
1
2
3
4
5
6
7
8
9
10

定义配置SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
1
2
3
4

输入ip:port/swagger-ui.html，默认swagger页面的结构

接口分类信息：例如可以区分定义外部接口和内部接口，用Swagger Docket实例的groupName分组显示

项目基本信息：通过Swagger Docket实例的apiInfo方法描述

接口列表：Swagger Docket实例中指定过滤条件后，Controller层所有接口的展示与调用

定义Docket实例

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docker(){
        // 构造函数传入初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了项目基本信息的必要条件
                .apiInfo(apiInfo())
                //groupName 指定接口的分组信息
                .groupName("groupTest")
                //配置是否启用Swagger，如果是false，在浏览器将无法访问。生产环境需要置为false
                .enable(true)
                .select()
                //apis： 添加过滤条件,
                //.apis(RequestHandlerSelectors.basePackage("com.swagger.demo"))
                //paths： 这里是控制哪些路径的api会被显示出来，比如下方的参数就是除了/test以外的其它路径都会生成api文档
                //.paths((String test) -> !a.equals("/test"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("项目名称：name", "项目连接地址：http://xxx.xxx.com/", "联系人邮箱：XXX");
        return new ApiInfo(
                "标题内容",
                "描述内容",
                "版本内容：v1.0",
                "链接：http://terms.service.url/",
                contact,
                "许可",
                "许可链接",
                // 扩展信息
                new ArrayList<>()
        );
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

实体类定义

@ApiModel 用于swagger标记实体类

@ApiModelProperty用于swagger标记实体类属性

样例说明

@Data
@ApiModel(description = "用户信息")
public class InfoVO {

    @ApiModelProperty(value = "名称",required = true)
    private String name;

    @ApiModelProperty(value = "价格",example = "1.0")
    private BigDecimal price;

    @ApiModelProperty(value = "状态 0-未删除 1-逻辑删除",allowableValues = "0,1",example = "0")
    private String status;

    @ApiModelProperty(value = "时间",allowEmptyValue = true)
    private LocalDateTime localDateTime;

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

接口定义

@Api 注解用于标注类为swagger资源

@ApiOperation注解一般用于方法上，用作一个HTTP请求的方法描述

样例说明

@Api(tags = "swaggger测试")
@RestController
public class TestController {

    @ApiOperation(value = "总结性描述测试1")
    @PostMapping("/test1")
    public APIResult<String> test1(InfoVO infoVO){
        //TODO save operation
        ...
        return APIResult.ofSuccess("数据保存成功");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

swagger页面显示结果

基于swagger同步yapi规范

因为swaggger对代码的浸入性很强，所以我们尽可能的定义yapi中所需要的接口信息，摒去无用的定义。

实体类定义

非代码生成器生成的与数据库表结构相关联的domain类，例如与前端交互的VO类、与外部服务进行数据交换的DTO类，需在类头加上@ApiModel注解，在类属性加上@ApiModelProperty注解，便于补全接口文档的同时又可替换类注释。

@ApiModel注解

@apiModel主要用于标记实体类，定义格式：

@ApiModel(description = "xxx") 
public class XXX
1
2

该属性定义后，接口返回类型为Object时，yapi中会显示对象的备注

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ugOBaC7J-1673502457803)(null)]

@ApiModelProperty注解

@ApiModelProperty用于标记swagger实体类属性，定义格式：

@ApiModelProperty(value = "xxx",required = true)
private String xxx;
1
2

定义该属性用于展示在yapi接口中请求参数、返回参数的字段备注、是否必须项信息

接口定义

@Api注解

@Api用于标注类为swagger资源，定义格式：

@Api(tags = "XXX")
@RestController
public class XXXController
1
2
3

定义tags属性，主要用于维护yapi中的文档分类

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-3sOgv8Uv-1673502457709)(null)]

@ApiOperation注解

@ApiOperation用作一个HTTP请求的方法描述，定义格式：

@ApiOperation(value = "xxx")
@PostMapping("/xxx")
public APIResult<String> xxx(){}
1
2
3

定义ApiOperation的value属性，主要用于维护yapi中主分类的接口信息

@ApiImplicitParams和@ApiImplicitParam

@ApiImplicitParams和@ApiImplicitParam组合使用作用于方法上，这里主要用于定义yapi中请求参数的header属性。如非必须尽量不要使用，代码侵入性太严重了。

定义格式：

@ApiImplicitParams({
      @ApiImplicitParam(paramType = "header", name = "xxx", value = "xxx", dataType = "xxx", required = true),
      ...
})
1
2
3
4

yapi中显示结果以及定义方式:

注意事项

例如以下的几个接口，均不符合标准

//第一种情况 入参为JsonStr  出参为Map
@ApiOperation(value = "错误示范1")
@PostMapping("/errTest1")
public Map<String,Object> errTest1(@RequestBody String infoVo){
    //TODO save operation
    ...
    Map<String,Object> res = new HashMap<>();
    res.put("msg","ok");
    res.put("code",200);
    res.put("data","1");
    return res;
}




//第二种情况 使用javabean传参、出参，但javabean中包含Map、Object的情况
@Data
@ApiModel(description = "test4")
public class Test4 {
    @ApiModelProperty(value = "名称",required = true)
    private String name;
    
    //object属性 swagger不能识别
    @ApiModelProperty(value = "值")
    private Object value;
    
    //尽可能将map、object定义成新的javaBean
    @ApiModelProperty(value = "用户信息")
    private InfoVO infoVo;
} 

@ApiOperation(value = "错误示范2")
@PostMapping("/errTest2")
public APIResult<Test4> errTest2(Test4 test4){
    //TODO save operation
    ...
    return APIResult.ofSuccess(test4);;
}


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

上方定义的接口生成的swagger文档示例如下

yapi中的接口展示:

错误示例定义出来的接口文档，增大了接口联调的测试难度。接口数据同步到yapi上，因为缺失了必要的字段信息，也会导致接口和代码的可阅读性较差。

所以在实际接口定义过程中，尽量使用javaBean，而不要使用Map、Object、JSON String等方式定义接口的出入参。如果是通用返回结果集，尽量使用泛型替换Object。