接口文档编写实例：程序员如何写出清晰可用的API说明

接口文档长什么样？先看个真实例子

你在公司做前端开发，新项目要调用用户登录接口。后端同事发来一段文档：

{
  "url": "/api/v1/login",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "request": {
    "username": "string, 必填, 用户名",
    "password": "string, 必填, 密码"
  },
  "response_success": {
    "code": 0,
    "msg": "success",
    "data": {
      "token": "用户令牌",
      "expire": "过期时间戳"
    }
  },
  "response_fail": {
    "code": 1001,
    "msg": "用户名或密码错误"
  }
}

这就是一份典型的接口文档，虽然格式简单，但关键信息都齐了：请求地址、方式、参数、返回结构。

为什么接口文档不能只写代码？

有些后端觉得“你直接看代码不就知道了”，可现实是：前端、测试、产品都不是读代码高手。比如产品经理想确认登录失败有几种提示，翻源码得花半天。如果文档里清清楚楚写着“错误码1001代表账号密码错误”，一目了然。

标准接口文档该包含哪些内容

以常见的 RESTful API 为例，一个完整接口描述应包括：

• 接口名称：比如“用户登录”
• 请求路径：/api/v1/login
• 请求方法：POST
• 请求头（Headers）：如 Content-Type、Authorization
• 请求参数：字段名、类型、是否必填、说明
• 成功响应：状态码、返回示例、字段解释
• 错误响应：常见错误码及含义
• 备注：比如“首次登录需短信验证”

再来看一个更规范的 Markdown 实例

很多团队用 Markdown 写文档，结构清晰又方便转成网页。比如：

# 用户登录

**URL** : `/api/v1/login`

**Method** : `POST`

**Headers** :
- Content-Type: application/json

**Request Body** :
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 登录密码 |

**Success Response** :
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire": 1735689245
  }
}
```

**Error Response** :
- `1001`: 用户名或密码错误
- `1002`: 账号被锁定

**Note** : 连续输错3次将锁定账户5分钟

这种写法在 GitHub 或内部 Wiki 上都很常见，新人接手项目时能快速上手。

工具让文档更高效

手动维护文档容易出错。现在很多人用 Swagger（OpenAPI）自动生成。只要在代码里加点注释，就能输出可视化界面。

比如用 Spring Boot 开发，加上 @ApiOperation 注解，启动服务后访问 /swagger-ui.html 就能看到所有接口，还能直接测试。

别忽视版本和变更记录

接口不是一成不变的。比如某天登录接口要求增加图形验证码，老文档没更新，前端按旧规则开发，联调时才发现问题。

建议在文档开头加个变更日志：

## 变更记录

- 2025-03-20 v1.1 增加 captcha_id 和 captcha 参数
- 2025-01-10 v1.0 初始版本

谁改的、什么时候改的、改了啥，一清二楚。

好文档是团队协作的基础

别把写文档当成负担。一份清晰的接口说明，能减少无数沟通成本。你写的不只是技术细节，更是给队友的一份使用说明书。就像家电包装里的操作指南，越明白越好用。