1、服务必须有完整描述
每一个服务都必须定义完整如下信息：
服务中文名
服务中文描述
服务联系人姓名
服务联系人邮箱
正例：
image.png
2、接口基本描述必须完整
每个服务的接口，包括Controller类和接口方法，都需要有接口的中文介绍描述。以让读者知道接口的基本功能及相关情况。
正例：
image.png
3、接口入参描述完整
接口的每个入参必须描述如下信息：
- 参数名
- 参数类型
- 参数描述
- 是否必填
- 示例
接口入参放在body中的，必须要是json格式，需要描述每个类、每个字段属性的如下信息：
- 字段名
- 字段类型
- 字段描述
- 是否必填
- 示例
正例：
入参信息描述完整
GET http://msr.jiatuidev.com/ai-article/v2/api-docs 展开源码
[图片上传失败...(image-f4ba09-1574405254233)]
入参如为body中时，每个字段信息完整
GET http://msr.jiatuidev.com/ai-article/v2/api-docs 展开源码
[图片上传失败...(image-e0be4e-1574405254233)]
4、接口返回值规范
接口返回值均使用JSON，按如下统一格式
ServiceResponse
|
1
2
3
4
5
6
|
{
"code"``: ``0``, ``#返回码
"data"``:{}, ``#返回数据
"msg"``: ``"string"``, ``#返回信息
...
}
|
对应代码中统一使用ServiceResponse类作为返回值，且必须声明ServiceResponse<T> 中的具体 T的类型。
data 属性约定：如为对象，需要像入参body一样，为每一个字段加上如下属性描述：
- 字段名
- 字段类型
- 字段描述
- 是否必填
- 示例
***code *属性约定：code 的值需要在返回码管理平台(参考：返回码管理平台 )定义。
如下为公共错误码，由基础框架统一识别处理，业务系统不需要特别逻辑。
image.png
正例：
GET http://msr.jiatuidev.com/ai-article/v2/api-docs 展开源码
image.png
不规范反例：
image.png
5、废弃接口规范
对于不再使用的接口，应该不再在swagger中展现。
6、数据类型约束
参见：003.开发规范 之第5条。
7、接口命名规范
7.1 接口路径命名规范
对于CRUD类型的接口，命名路径上应体现对应实体名称，且实体名称应和数据库中对应的表名按一定规律对应：
实体名称如为多个单词组成，数据库表名应为小写字母加下划线隔开单词，接口路径上的实体名称可以相同，但要将下划线转为中横线。
对于向前端提供的地址，如果路径的命名暴露了开发的细则，则应换一个不太明显的词语并作好路径映射。
数据库表名如有公共前缀的，接口上的实体名称可不用包含这部分公共前缀。
接口路径部分多个单词由中横线隔开，不使用驼峰命名法，字母需要为小写，接口GET参数仍然使用驼峰命名方式。
正例：
数据库表名：t_card_member_user_relation
接口命名：GET /xxx/card-member-user-relation/{id}
7.2 字段属性命名规范
字段属性和数据库字段有对应的，命名上应保持统一，对于多个单词的情况，数据库中的字段为下划线隔开全小写字母，接口中的字段属性对应为驼峰命名，首字母小写。
正例：
数据库字段名：company_id
接口对应的属性名：comanyId
8 接口参数规范
非GET类型的接口，不能使用Url参数，只能使用BODY中传JSON格式数据作为参数。
网友评论