简介

OpenAPI 规范与 Swagger 工具链，用于描述、文档与代码生成。

下列说明侧重开发者如何在本站 API 目录选型后，用该工具完成联调与文档协作；具体功能与版本以官方产品为准。

类型

API 文档

相关链接

https://swagger.io/

能做什么

Swagger/OpenAPI toolchain 用 machine-readable 规范描述 REST API，生成交互文档（Swagger UI）、客户端 SDK、Mock 与契约测试输入，减少文档漂移。

典型工作流

  • 编写或从代码注解导出 openapi.yaml
  • Swagger Editor 校验语法与示例
  • Swagger UI 给前后端/合作方浏览
  • 结合代码生成器产出客户端

何时用

设计阶段先定契约、对外 API 需要自助文档、或希望 CI 做 breaking change 检测时。

注意点

规范与实现必须同步审查；示例要含错误响应；版本号策略写进 README。仅文档漂亮而缺示例请求，联调仍会扯皮。

与 API 目录配合

若上游提供 OpenAPI 文件，可挂到 Swagger UI 供团队浏览；没有官方规范时，也可先手写最小 openapi.yaml 描述核心路径，再随迭代补全。与极旺目录中的 fact-list 字段对照，避免文档漏写鉴权头。

团队实践

在 PR 模板中要求「是否更新 OpenAPI」，并用 diff 工具对比 breaking change。对外发布时固定文档 URL，方便从极旺导航跳转到你们托管的最新规范。Mock Server 可先供前端并行开发，后端实现后再切换真实 base URL。安全评审时把 paths 与 securitySchemes 单列一节，避免漏审 OAuth scope。