BlessingCR’s Blog
BlessingCR’s Blog

API文档规范

以下屁话都是乱说的, 我是个忠实的RESTful用户

建议遵循 https://cloud.google.com/apis/design?hl=zh-cn

以下内容仅供特殊情况下使用

API文档规范

API文档作为详细设计的一部分,其必须在开发之前完成。为提高前后端协同效率,详细设阶段需要提供所有前后端和对外接口;RPC接口可后续补充;


0. 通用规范

URL要求

  1. 需要包含接口URL(具体域名或IP可不写)
  2. URL需要包含通信方式http / https / ws 等
  3. URL使用-连接多个单词
  4. 常用动词, 见下动词表,动词可自定义,但curd类功能如无特殊情况请参照动词表;
  5. URL不能包含特殊字符和敏感词汇,除非这些字符有特殊的编码需求
  6. 必须包含/api/admin-api 或 /api/rpc-api
  7. url应该存在层级关系,除固定前缀外,应为/项目简称/模块名/[二级模块名,如有]/功能名/动词/[id, 如有]
URL结尾动词 说明
create 创建、新增
update 编辑、修改
delete 删除
get 查询、获取
page 分页查询
export 导出
import 导入
样例:
- 创建角色:/admin-api/cl/acct/role/create
- 修改角色:/admin-api/cl/acct/role/update
- 删除角色:/admin-api/cl/acct/role/delete、 /admin-api/cl/acct/role/delete/{id}
- 获取角色信息:/admin-api/cl/acct/role/get、/admin-api/cl/acct/role/get/{id}、/admin-api/cl/acct/role/get-by-user
- 获取角色分页:/admin-api/cl/acct/role/page
- 导出角色:/admin-api/cl/acct/role/export
- 导入角色:/admin-api/cl/acct/role/import

接口描述要求:

  1. 必须包含功能描述
  2. 加密与否,签名与否 ,如有需说明加解密方式与签名方式
  3. 如有特殊需要注意的,需注明

请求方式要求

  1. 目前仅使用get / post; 且必须写明get / post
  2. 对于涉及数据修改的操作(如更新,删除),应使用POST请求。POST请求可以发送大量数据,且数据不会显示在URL中,特别的,分页查询应为POST
  3. 对于数据查询的操作,且无涉及敏感内容,应使用GET请求
  4. 所有GET请求不应该携带body, 避免中间件过滤

请求字段要求

  1. 请求参数,包括header与body,参数需要写明必填、类型、长度和意义,如需计算写明计算规则
  2. 如涉及常量,则必须描述所有常量及其意义
  3. 涉及前后端传参或对外接口时,Long类型字段必须使用String类型避免精度丢失
  4. 字段的命名应遵循驼峰命名法
  5. 编码使用UTF-8

响应要求

  1. 响应参数,参数需要写明必填、类型、长度、意义和mock值,如需计算写明计算规则
  2. 必须包含code, data, msg字段; 其中data为空的时候设置为{},不可为null; code正常是为0,其余情况下为错误码
  3. 无特别设计时,相应正常以及业务异常时,HTTP STATUS均为200; 如特殊情况,需注明
  4. 编码使用UTF-8

1. 内部非前后端接口文档额外规范(包括但不限于RPC, MQ等)

MQ类:

  1. 必须写明Topic, 消息类型,TAG等基础信息
  2. 如有加解密方式,必须写明
  3. 写明消息体,以及消息内具体字段含义
  4. 建议使用@link 关联涉及的producer, consumer

RPC类:

  1. 推荐在url中加上接口版本
  2. 如果header中需要特殊参数,必须说明
  3. 返回值应用CommonResult包裹,特殊比特流返回等除外
  4. 异步接口需要特殊注明,如提供后续查询结果接口,注明
  5. 如果为批量接口,使用列表或者其他集合类包裹所有结果,不要有任一元素直接失败返回整体失败。

2. 外部接口文档额外规范

强制要求:

  1. 每个接口必须包含:
    1. 功能描述
    2. 通信方式 —— [https, http, tpc, websocket等]
    3. 数据格式 ——[json, xml等]
    4. 请求示例与响应实例
    5. 有可能返回的错误码及其含义
    6. SDK(如有)
  2. 对外HTTP接口强制要求HTTPS
  3. 涉及敏感字段传输必须使用POST, 且考虑加密传输
  4. 金钱类参数必须使用String类型传输
  5. 时间传输如果使用String类型,需要说明时区
  6. mock字段参数或结果,不应该出现真实的名称,但可以是本公司或者合作公司名称

推荐要求:

  1. 推荐包含:
    1. 对接准备
    2. 快速入门
    3. 各具体场景下业务方案 / 风控方案 / 推荐配置
    4. 接口之间的时序图/流程图
    5. 各语言调用接口的样例代码 / Postman项目文件
    6. 服务支持协议
    7. 常见问题
    8. 版本号与版本说明
  2. header中,如特别不需cdn缓存的接口,推荐加上cache-control
  3. 不推荐返回跨域header为*
  4. 推荐使用/v1,/v2之类的待版本号的url,用于同时支持多版本服务

附录标准字段

本节介绍了需要类似概念时应使用的一组标准消息字段定义。这将确保相同的概念在不同 API 中具有相同的名称和语义。

发表回复

textsms
account_circle
email

BlessingCR’s Blog

API文档规范
以下屁话都是乱说的, 我是个忠实的RESTful用户 建议遵循 https://cloud.google.com/apis/design?hl=zh-cn 以下内容仅供特殊情况下使用 API文档规范 API文档作为详细设计的一部分,其必须…
扫描二维码继续阅读
2024-03-01