为什么API文档要集成鉴权说明
做前后端联调时，最怕啥？不是接口字段变来变去，而是连不上——因为没带鉴权信息。很多团队在写API文档时，只写请求路径和参数，却把鉴权方式一笔带过，结果开发对接时反复问“token放哪？”、“用哪种加密？”。
其实，一个高效的API文档，应该把鉴权方式清清楚楚地嵌进去，让使用者一看就懂，不用翻聊天记录、不用查内部Wiki。
常见的鉴权方式有哪些
目前主流的API鉴权方式有几种，每种适用场景不同：
1. API Key
最简单的方案，通常放在请求头里。比如：
Authorization: ApiKey abc123xyz适合内部系统或第三方服务接入，安全性要求不高的场景。生成文档时，可以直接在示例请求中注明这个Header。
2. Bearer Token（JWT）
用户登录后返回JWT，后续请求带上：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...这种在现代Web应用中非常普遍。文档里不仅要写怎么传，还得说明token获取路径，比如先调用/api/login拿到token。
3. OAuth 2.0
适用于开放平台，比如微信登录、GitHub第三方授权。流程复杂，涉及redirect_uri、client_id、scope等参数。文档需要画出流程图，并标注每个步骤的接口调用方式。
4. HMAC 签名
对安全性要求高的场景，比如支付类接口。每次请求都要用密钥对参数签名，防止被篡改。文档里必须给出签名算法示例，否则开发者根本没法对接。
如何在文档生成工具中体现鉴权
现在很多人用Swagger（OpenAPI）、Postman、YApi这类工具自动生成文档。关键是怎么把鉴权信息自然地融进去。
以OpenAPI 3.0为例，可以在components里定义安全方案：
components:
securitySchemes:
api_key:
type: apiKey
in: header
name: X-API-Key
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT然后在具体接口上声明使用哪种：
security:
- bearerAuth: []这样生成的页面会自动提示用户需要认证，并在“Try it out”按钮测试时预留输入token的位置。
别忘了给开发者留个“测试入口”
光写规则不够，最好在文档里加一个“获取测试Token”的按钮或接口。比如：
POST /api/debug/token
{"role": "admin"}方便前端同事快速拿到可用凭证，省得等后端手动开权限。
有些团队还搞了个小页面，填完账号密码点一下，直接生成带token的curl命令，复制就能跑，效率提升不止一点半点。
文档更新要跟上鉴权变更
有一次我们升级了鉴权机制，从API Key换成HMAC，但文档没及时改。结果新接入的合作伙伴连着三天对接失败，最后发现是他们按旧文档写的签名逻辑。
所以只要鉴权方式有变动，文档必须同步更新，最好在CI流程里加上检查项，确保OpenAPI文件里的security配置和代码一致。
可以考虑在接口注释里直接写明鉴权类型，比如用Swagger注解：
/**
* @security bearerAuth
*/这样生成文档时能自动提取，减少遗漏。