接口文档设计，产出

  1. 接口文档
  2. 数据库表结构
  3. 接口文档格式
    1. Swagger
    2. YAPI
    3. EasyMock
    4. MarkDown

接口文档设计

开发流程

  1. 需求
    1. 理解需求
    2. 关键功能技术评审，预研
  2. 开发
    1. 设计数据库表接口
    2. 设计 API接口文档
    3. 接口功能实现
  3. 测试
    1. 接口联调，自测，提交测试
  4. 上线
  5. 复盘

文档格式

分页结构

  1. {
  2.   "current": 1, // 当前页码
  3.   "pageSize": 10, // 每页条数，默认10
  4. }

API返回结构

  1. {
  2.   "code": 0, // 状态码 0：成功，非0：失败
  3.   "data": [], // 返回结果, 204状态没有 data
  4.   "msg": "错误信息" // 错误信息
  5. }

API版本思维

  • api分版本，v1， v2，v3，兼容业务变动
  • api版本管理
  • 放在路径里面
  • 放在查询参数里面
  • 放在 header里面
  1. /api/user
  2. /api/v1/user
  4. /api/v2/user
  • 如果不写 v1，默认就是v1，例如 /api/user