[Swagger] Swagger开发规范

2018-08-25 本文已影响24人离兮丶斜阳

title: Swagger开发规范 [推荐]
date: 2018-08-18 20:22:00
categories:

Spring Components
tags:
spring
springfox-swagger

Springfox Swagger 和Spring的整合已经让我们可以动态的生成接口文档了，但是接口文档的定义需要遵循一定的规范，才能大大提高项目团队间的接口对接效率。

Swagger开发规范 [推荐]

swagger JSON文档生成

maven-surefire-plugin(指定Swagger测试用例)

notes\env\maven\2018-06-27-maven-surefire-plugin.md

虚拟注入和扫描

notes\spring\components\2018-06-08-springfox-swagger-jenknis.md

接口定义规范

接口分组
接口组描述

鉴权方式描述

在description中描述该组接口的鉴权方式，可以使用超链接等方式也可以直接在其中说明

能力级描述

/** 在description中描述该组接口的能力集 */
 new ApiInfoBuilder().contact(contact).description("api描述1111").version("1.0").title("标题").build();

联系人信息

/** 在contact中描述联系人信息，接口得有负责人 */
new ApiInfoBuilder().contact(contact).description("api描述1111").version("1.0").title("标题").build();

配置类注解是否包含基本注解（Spring 注入）

@Configuration
@EnableSwagger2
public class SwaggerConfig {...}

Controller控制器类(或在接口Interface中定义)

使用注解@api时是否对value description tags属性都进行了描述

    @Api(value = "API测试", description = "API接口描述，主要作为示例使用", tags = "测试1")

注解@api的description属性是否描述了该类接口的概括描述和能力集

    @Api(value = "API测试", description = "API接口描述，能力1，能力2...", tags = "测试1")

注解@apioperation是否对value、notes、tags属性进行描述

    @ApiOperation(value = "call_1接口", notes = "call_1接口描述", tags = "测试1")

注解@apioperation的属性notes是否描述了接口的详细情况和能力

notes描述在pdf中的排版

"\t\tHead: " +
"\t\t\t\t PublicKey -> 公钥\n" +
"\t\t\t\t P -> P参数\n" +
"\t\t\t\t G -> G参数\n" +
"\t\t\t\t Token -> 双向认证令牌\n" +

多个简单参数情况下是否使用注解@ApiImplicitParams

    @ApiImplicitParams({
        @ApiImplicitParam( value = "姓名", name = "name", required = true, paramType = "query", dataType = "string"),
         @ApiImplicitParam( value = "年龄", name = "age", required = true, paramType = "query", dataType = "int"),
        @ApiImplicitParam( value = "日期", name = "birthday", required = true, paramType = "query", dataType = "date",    defaultValue = "2017-01-01")
 })

注解@ApiImplicitParam的属性value, name, required, paramType, dataType , defaultValue 等是否都有描述

    value = "日期", name = "birthday", required = true, paramType = "query", dataType = "date", defaultValue = "2017-01-01"

数据传输对象注解

返回数据对象基类是否使用了泛型定义

    @ApiModel(value = "返回数据对象", description = "描述返回数据对象")
    public class Result<T>{}

复杂出入参是否使用数据传输对象进行封装


@ApiModel(value = "返回数据对象", description = "描述返回数据对象")
public class Result<T> {

   @ApiModelProperty(required = true, value = "返回码", dataType = "int", example = "0", position = 0)
   protected int code;

   @ApiModelProperty(required = true, value = "返回信息", dataType = "string", example = "买买买", position = 1)
   protected String message;

   @ApiModelProperty(required = true, value = "其他返回信息", position = 2)
   protected T data;
}

数据传输对象类名上是否有注解@Apimodel

@ApiModel(value = "数据对象", description = "描述返回数据对象")
public Class Dto1{}

数据传输对象的属性注解@apimodelproperty是否对属性required, value, dataType, example, position都有描述(position字段在1.5.X后被废弃，可以不进行设置)

    required = true, value = "返回码", dataType = "int", example = "0", position = 0

数据对象属性需要自定义名称的是否使用了@JsonProperty注解

@ApiModelProperty(required = true, value = "测试自定义名称", dataType = "string", example = "AAACCDSF", position = 3)
@JsonProperty(value = "AAC")
private String AAC;

备注

Swagger接口定义要求明确的出入参的必要性：

1、自动生成接口文档，可以直接生成返回数据体
2、前端开发依赖swagger.json生成的静态Mock Server，可直接模拟构建前端请求返回的数据体。
3、接口说明注解写得越详细，后期联调和前端自主开发都会大大节约时间，这也是前后端分离的初衷。

返回参数要求

1、ActionResult的返回数据体以泛型传入

return new ActionResult<Dto1>();

2、泛型支持类型 [ 前提是返回参数明确 ]集合对象包裹的Dto对象

List<Dto1>、List<Map<String,Dto1>>、Map<String,Dto1>、Dto1 { Dto2,Dto3,…}(对象嵌套)

3、不支持以Object形式、JsonObject形式返回参数

接口描述

ApiModelProperty

dateType

- 类名（引用路径）


/*如果该类不存在或是直接使用名称[无法通过Class.forName(...)生成]，原来的返回类型Original会被保留，*/

@ApiModelProperty(dataType = "com.qualified.ReplacedWith")
public Original getOriginal() { ... }

- baseTypes

     private static final Set<String> baseTypes = newHashSet(
      "int",
      "date",
      "string",
      "double",
      "float",
      "boolean",
      "byte",
      "object",
      "long",
      "date-time",
      "__file",
      "biginteger",
      "bigdecimal",
      "uuid");

微信公众号

架构探险之道

扫码关注或搜索架构探险之道获取最新文章，坚持每周一更，坚持技术分享的我和你们一起成长 ^_ ！