API 文档怎么维护和自动生成，Swagger/OpenAPI

API 文档不该靠人手写维护，正确做法是「代码即文档」：用 OpenAPI 规范描述接口，从代码注解或设计文件自动生成，再用 CI 卡住不合规的提交。这样文档和代码在同一个 Git 仓库、同一次发版里更新，不会出现「接口改了文档还是半年前的」这种腐化。

Swagger 和 OpenAPI 是什么关系，有什么区别？

结论：OpenAPI 是规范（写文档的格式标准），Swagger 是一套工具链，两者不是一回事。2015 年 SmartBear 把 Swagger Specification 捐给 Linux 基金会下的 OpenAPI Initiative，规范改名为 OpenAPI Specification（OAS）；Swagger 这个名字保留给工具，比如 Swagger UI（渲染网页版文档）、Swagger Editor（在线编辑器）、Swagger Codegen。

版本上要分清：OAS 2.0 就是老的 Swagger 2.0；OAS 3.0 发布于 2017 年 7 月，用 components/schemas 取代了 2.0 的 definitions，用 requestBody 取代 body 参数，新增 oneOf/anyOf 组合；OAS 3.1 发布于 2021 年 2 月，与 JSON Schema 2020-12 完全对齐，nullable 改成标准的 type: ["string","null"]。新项目直接上 3.1，老项目 3.0 也够用。

怎么从代码自动生成 OpenAPI 文档？

结论：主流后端框架都有成熟插件，加一个依赖、写少量注解就能出 /openapi.json 和可视化页面。按技术栈选：

• Java + Spring Boot 3：用 springdoc-openapi-starter-webmvc-ui（2.x 版本对应 Boot 3，1.x 对应 Boot 2），启动后访问 /swagger-ui/index.html 看页面、/v3/api-docs 拿 JSON。注意别再用 springfox，它 3.0.0 停在 2020 年，Spring Boot 2.6 起默认启用 PathPatternParser，会直接报 Failed to start bean 'documentationPluginsBootstrapper' 启动失败。
• Python + FastAPI：零配置，框架自带 OpenAPI 3.1 输出，/docs 是 Swagger UI、/redoc 是 ReDoc、/openapi.json 是原始规范。
• Node + NestJS：装 @nestjs/swagger，在 main.ts 里 SwaggerModule.createDocument(app, config) 再用 SwaggerModule.setup('api', app, document) 挂载。
• Go：用 swaggo/swag，靠注释生成 docs/swagger.json。

设计优先（design-first）和代码优先，该选哪个？

结论：对外提供的开放 API 选设计优先，内部服务选代码优先。设计优先是先手写 openapi.yaml，评审通过后再生成代码：

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g spring -o ./server \
  --additional-properties=interfaceOnly=true

同一条命令换 -g typescript-fetch 就能给前端吐出类型安全的 SDK，省掉手工对接。代码优先则是先写 Controller 注解、再导出规范，适合迭代快的内部服务，代价是文档质量取决于注解写得多细。

怎么防止文档随时间腐化？

结论：把文档校验放进 CI，让「文档和代码不一致」变成构建失败。三件事必做：

1. 规范校验：npx @stoplight/spectral-cli lint openapi.yaml，能查出缺少 description、路径命名不规范、未定义 4xx 响应等问题。
2. 破坏性变更拦截：用 oasdiff breaking base.yaml revision.yaml 或 openapi-diff 对比，把「删除字段」「把可选参数改成必填」这类改动标红，要求人工确认。
3. 覆盖率门槛：在 CI 里断言生成的规范中每个接口都必须有 summary、responses 覆盖 200/400/401/500、以及请求体 example。

另外约定：字段重命名必须走弃用流程——先加 deprecated: true 并保留至少一个版本周期，再删除，否则调用方会直接炸。

一份能用的接口文档至少要写哪些字段？

结论：每个接口必须写全 summary、参数说明、请求体 schema 带 example、全部可能的响应码、以及鉴权方式。鉴权在根节点 components.securitySchemes 里统一定义一次（如 type: http + scheme: bearer），再用 security 引用，不要每个接口重复描述。example 比 description 更有价值——Swagger UI 的「Try it out」直接拿它当默认值，对接方能少问一半问题。枚举值要列全，别写「传状态码」了事。

总结一句：规范选 OpenAPI 3.1，生成选框架自带的插件（Spring 用 springdoc、FastAPI 零配置、Nest 用 @nestjs/swagger），流程上把规范文件纳入 Git、把 spectral 和 oasdiff 塞进 CI。做到这三点，文档就变成了构建产物，而不是需要专门排期维护的负担。