Node.js / 系统课时

编写 API 文档

编写 API 文档

接口能返回数据还不等于能顺利联调;调用方还需要知道路径、参数位置、成功响应和失败响应的精确结构。本节用 OpenAPI 3.2.1 描述一个查询用户接口,让前后端可以按同一份契约实现、测试和排错。

学习目标

  • 用 OpenAPI 3.2.1 明确记录 HTTP 方法、路径参数、状态码和 JSON 响应结构。
  • 为成功与错误响应提供可复制的示例值,并让错误码保持机器可判断。
  • 用一组固定检查项验证文档是否足够支持联调,而不是只写自然语言说明。

把接口契约写成可执行结构

一条可联调接口至少应回答六个问题:使用什么方法、访问什么路径、参数从哪里传、参数类型与约束是什么、成功返回什么、失败时有哪些状态码和错误码。以 GET /api/users/{id} 为例,id 是路径参数,因此在 OpenAPI 中必须声明 in: path、required: true。

建议把稳定的机器契约写进 openapi.yaml,而把业务背景、调用时机等补充说明放在 description。本例按 OpenAPI 3.2.1 编写;如果团队现有生成器只声明支持 3.1.x,应使用其明确支持的版本并重新跑规范校验,不能只改版本号后直接发布。

用 OpenAPI 描述一个完整接口

下面这份文件只描述一个接口,但已经包含联调需要的关键内容:服务地址、路径参数、成功响应、400 参数错误、404 不存在,以及可复用的 User 与 Error Schema。

yaml
openapi: 3.2.1
info:
  title: Users API
  version: 1.0.0
servers:
  - url: http://localhost:3000
paths:
  /api/users/{id}:
    get:
      operationId: getUserById
      summary: 按 ID 查询用户
      parameters:
        - name: id
          in: path
          required: true
          description: 正整数用户 ID
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: '#/components/schemas/User'
              example:
                data:
                  id: 42
                  name: Ada
        '400':
          description: 路径参数不合法
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_ARGUMENT
                  message: id must be a positive integer
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: user not found
        '503':
          description: 依赖服务暂时不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: SERVICE_UNAVAILABLE
                  message: service temporarily unavailable
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
          minLength: 1
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string

生效后的契约很明确:GET /api/users/42 成功时必须符合 200 响应 Schema;id 不是正整数时返回 400,并使用 INVALID_ARGUMENT;用户不存在时返回 404,并使用 NOT_FOUND;依赖服务临时不可用时返回 503。实现代码若返回其他字段名或状态码,就应视为实现与文档不一致。

错误码与响应结构保持稳定

HTTP 状态码解决“哪一类失败”,业务错误码解决“具体是哪一种失败”。例如多个参数错误都可以使用 HTTP 400,但 error.code 应继续区分 INVALID_ARGUMENT、MISSING_FIELD 等情况,调用方才能稳定编写分支逻辑,而不是解析会变化的中文或英文 message。

推荐把错误响应固定成同一个外壳:顶层只有 error,其中至少包含 code 和 message。新增调试字段时也尽量放在 error 内,并明确它是否只在非生产环境出现,避免客户端把临时字段当成长期契约。

场景 HTTP 状态码 error.code 调用方处理
id=abc 或 id=0 400 INVALID_ARGUMENT 修正请求,不重试
用户记录不存在 404 NOT_FOUND 显示不存在或回到列表
数据库短暂不可用 503 SERVICE_UNAVAILABLE 可按退避策略重试

联调前做四项检查

第一项检查路径模板:/api/users/{id} 中每个花括号变量都必须有同名 in: path 参数,而且路径参数必须是必填。第二项检查状态码:实现可能返回的 200、400、404、503 都应在文档中出现,不能只写“成功”和“失败”两种笼统结果。

第三项检查 Schema 与示例是否一致,例如 User.id 定义为 integer,示例就不要写成字符串 "42"。第四项检查实现与文档的错误码是否逐字一致;把 NOT_FOUND 写成 USER_NOT_FOUND 都属于契约变化,需要同步修改调用方或版本说明。

把这四项作为合并接口代码前的检查清单,可以快速发现“路径写对了但参数位置错”“服务返回 404 而文档没写”“示例字段和真实响应不同”等联调问题。API 文档达到可联调标准的判定依据不是文字多少,而是请求与每一种预期响应都能从文档中被唯一确定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写 API 文档

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通