美文网首页
服务API规范V0.1.0

服务API规范V0.1.0

作者: Abby_3b3a | 来源:发表于2019-11-22 14:49 被阅读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> 中的具体 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格式数据作为参数。

相关文章

  • 服务API规范V0.1.0

    1、服务必须有完整描述每一个服务都必须定义完整如下信息: 服务中文名服务中文描述服务联系人姓名服务联系人邮箱正例:...

  • 使用Beego+Swagger构建更好的API服务

    一. 更好的API服务 在你已经在工作中写了很多版本,很多规范的API服务之后,你会发现,后端服务很多共性的工作需...

  • 03.WebSocket API - JAVA客户端/服务端AP

    WebSocket API - JAVA客户端/服务端API 规范包含在JavaEE7中,在包javax.webs...

  • 订单微服务 接口设计说明

    阅读只需要一分钟,转载请注明出处.(未完成. v0.1.0) api.qrder.dotnet.sdao ====...

  • JSM规范,消息传递机制

    JMS(JAVA Message Service,java消息服务)API是一个消息服务的标准或者说是规范,允许应...

  • 接口规范文档总结

    接口规范文档 具体内容如下: 一:协议规范 二:域名规范 三:版本控制规范 四:API路径规范 五:API命名规范...

  • 提测规范V0.1.0

    执行阶段开发阶段,开发完成并自测通过后。 执行人开发人员、产品经理 规范内容一、提测条件1、 项目当前版本涉及的需...

  • tapd管理规范V0.1.0

    执行阶段测试阶段,统一缺陷录入的管理,便于开发更高效的识别。 执行人测试人员,开发人员,产品人员,设计人员 规范内...

  • 设计验收规范V0.1.0

    执行阶段 测试阶段 执行人 UI设计师、交互设计师 规范内容 对比开发测试包与UI设计稿对比还原度,由UI设计师及...

  • 线上评审规范V0.1.0

    执行阶段部署发布阶段,由测试负责人、项目经理、相关运维人员执行。 执行人项目管理人员+测试组+运维组,协调执行落地...

网友评论

      本文标题:服务API规范V0.1.0

      本文链接:https://www.haomeiwen.com/subject/jqqqwctx.html