Swagger 规范及API设计规范

JackPan
1,574 阅读3分钟

1 参数规范

参数规范提出的参数为必须填写，其他的属性根据自行需要添加。
1.1 使用@ApiModel描述与前端的交互类。
属性：

  • value描述类名
  • description描述类的作用

示例：

@ApiModel(value = "ApiModelTest", description = "用于测试ApiModel的作用")
public class ApiModelTest {
    // init data
}

1.2 使用@ApiModelProperty描述交互类的参数。
属性：

  • value描述参数作用
  • required明确指明该参数的强制性
  • hidden真值用于隐藏参数
  • example 提供给前端的测试例子

示例：

@ApiModelProperty(value = "参数作用", required = true, example = "test-id")
private String testProperty;

1.3 使用Hibernate Validator内注解验证参数的有效性，以下只举几个例子说明，具体深入用法，查阅文档即可。
示例：

@Pattern(regexp = "^[\\u4e00-\\u9fa5_a-zA-Z0-9]+$",message = "正则表达式验证")
@NotBlank(message = "不为空且不为空字符串")
@Email(message = "邮箱验证")

1.4 使用@Api描述提供给前端的controller类 属性：

  • description描述controller的作用

示例：

@Api(description = "测试控制器")
public class TestController {
}

1.5 使用@ApiOperation描述controller类中API方法的作用。
属性:

  • value描述该方法的作用

示例：

@ApiOperation(value = "获取测试用例子")
public Instance testInstance() {
}

1.6 使用@ApiImplicitParams和@ApiImplicitParam描述API方法参数，@ApiImplicitParams用于多个参数描述（内部包含多个@ApiImplicitParam），@ApiImplicitParam用于单个参数描述。注：使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解，@RequestBody与@ApiModel搭配使用。
属性：

  • name 参数名称
  • value 描述参数作用
  • paramType 参数放置位置。可选参数：header--请求参数的获取：@RequestHeader；query--请求参数的获取：@RequestParam；path（用于restful接口）-- 请求参数的获取：@PathVariable；body（不常用）；form（不常用）。

示例：

@ApiImplicitParams({
        @ApiImplicitParam(name = "testId", value = "测试Id", required = true),
        @ApiImplicitParam(name = "testStatus", value = "测试状态", required = true)
})
public ResultModel<Test> updateStatus(int testId, byte testStatus) {
    return ResultModel.success(test);
}

2 API设计规范

2.1 保证简洁明了
我们需要确保API的基本URL很简单。例如，如果我们要设计产品的API，则应将其设计为

/products
/products/12345

第一个API是获取所有产品，第二个API是获取特定产品。

2.2 使用名词而不是动词
许多开发者都会犯此错误。他们通常会忘记我们拥有能够更好地描述API的方式，但最终在API URL中使用动词。例如，获取所有产品的API应该是：

/products

而不是如下图所示

/getAllProducts

2.3 使用正确的HTTP方法
RESTful API有多种方法来指示我们将要使用此API执行的操作类型。

  • GET — 获取资源或资源集合.
  • POST — 创建资源或资源集合。
  • PUT/PATCH — 更新现有资源或资源集合。
  • DELETE — 删除现有资源或资源集合。

我们需要确保对给定的操作使用正确的HTTP方法。

2.4 使用查询参数
有时我们需要一个API，该API不仅要通过id获取数据，还应该有更多的作用。在这里，我们应该利用查询参数来设计API。

  • /products?name=’ABC’ 更好于 /getProductsByName
  • /products?type=’xyz’ 更好于 /getProductsByType

这样可以保证设计简单，并且避免过长的URL。

2.5 版本控制
API的版本控制非常重要。许多不同的公司以不同的方式使用版本，有些使用版本作为日期，而有些使用版本作为查询参数。通常版本参数作为查询资源的前缀。如下所示：

/v1/products
/v2/products

应用避免使用/v1.2/products，因为这意味着API会经常更改。 同样，URL中的点（.）可能不容易看到。因此，尽可能保持简单。 始终保持向后兼容性是一个很好的做法，这样，如果更改API版本，使用者可以在使用原先版本的同时，有足够的时间转到下一个版本。

以上API设计规范摘抄我先前阅读的英语文章RESTful API Design — Step By Step Guide，Google搜索下就可以找到，本文选取了部分常用的设计规范进行人工翻译，如果兴趣的同学，可自行进行深入阅读。

avatar
文章
阅读
粉丝