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

  • I’ve been browsing online more than three hours lately, yet I by no means discovered any attention-grabbing article like yours. It is beautiful price enough for me. In my view, if all web owners and bloggers made just right content as you probably did, the net can be a lot more useful than ever before.

    2 月前 回复
  • What¦s Happening i am new to this, I stumbled upon this I have discovered It positively useful and it has helped me out loads. I am hoping to give a contribution & assist other users like its helped me. Good job.

    16 小时前 回复

BlessingCR’s Blog

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