OpenAPI Specification

适合为前后端定义可审查的接口契约，并作为文档、类型生成、Mock 和契约测试的输入。规范文件本身不会实现接口、验证权限或保证服务端返回内容一定符合描述，发布前仍需把文档与真实服务和消费者测试连接起来。

维护时要同时描述成功、错误、参数、状态码、分页、认证和兼容性规则；不要只记录一个理想的 200 JSON。规范文件中的示例、测试凭据和用户数据也应脱敏。本条只收录 OpenAPI Initiative 的公开规范和开源维护仓库，不包含商业 API 管理或托管服务。