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。
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 文档达到可联调标准的判定依据不是文字多少,而是请求与每一种预期响应都能从文档中被唯一确定。