服务API规范V0.1.0

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的类型。

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格式数据作为参数。