6.2 OpenAPI与自动文档：代码即契约
6.2 OpenAPI 与自动文档：代码即契约
OpenAPI 是从 FastAPI 代码自动生成的机器可读接口规范：第 2 章写在签名与模型里的类型、约束、示例，在这里汇总为一份 JSON 文档，驱动交互式界面、客户端代码生成与契约测试。本节讲元数据定制、文档组织、错误响应声明，以及把这份 JSON 当"活契约"消费的三种工程方式。
本节能力目标
阅读完本节，你应当能够：
- 定制应用级元数据与接口级描述，让文档自解释；
- 用标签组织接口分组，用 summary 与 description 控制文档层级；
- 用 responses 参数显式声明错误响应的形态；
- 评估客户端代码生成在团队协作中的适用性；
- 部署文档的安全策略（内网、鉴权、关闭）。
文档从哪来：一条早已铺好的路
回顾一下数据流：路由签名的类型标注与 Query、Path 元数据（第 2 章）、Pydantic 模型的字段约束与 examples、依赖的 security 声明（第 5 章）——这些散落在代码各处的声明，被框架汇总成一份符合 OpenAPI 规范的 JSON，默认暴露在应用的 openapi.json 路径，并渲染出两个界面：docs（Swagger UI，交互式）与 redoc（阅读式）。
这件事的工程意义要拉开看。传统协作链路里"接口文档"是一份手工维护的独立产物，与代码存在永恒的同步差；OpenAPI 时代文档是编译产物——代码是唯一事实源，文档永远与运行行为一致，因为它们本是同一份数据的两种视图。前端抱怨文档过期、后端抱怨改文档麻烦，这类摩擦在源头被消除。
让文档配得上"给人看"
自动生成的是骨架，可读性靠三处人工投入。
应用级元数据：
app = FastAPI( title="订单服务 API", version="2.1.0", description="订单的创建、查询与状态流转。" "所有时间字段为 UTC ISO 格式。", )
description 支持长文本（换行分段），把全局约定写在这里：分页规则、错误体格式、认证方式。这是文档的"首页公告"，价值密度最高的一块。
接口级，docstring 与 summary 的分工：
@app.post("/orders", response_model=OrderOut, summary="创建订单", tags=["订单"], responses={409: {"description": "库存不足或重复提交"}}) def create_order(payload: CreateOrder): """ 创建一笔新订单。 幂等性：携带相同 request_id 的重复请求返回原订单而非新建。 库存扣减发生在异步任务中，下单成功不代表库存最终成立。 """ ...
summary 是列表页的一行话，docstring 是详情页的正文——业务语义（幂等行为、异步副作用）写在这里，它们无法从类型推导，恰恰是联调时最需要的信息。tags 参数把接口分进分组，文档页按标签折叠，几十个接口的服务立刻可导航。responses 参数补充文档对错误形态的描述：默认只展示 422（校验）与声明的成功码，409、403 这些业务错误要显式列出，前端才能提前写好对应处理——呼应第 4 章"错误也是契约"的主张。
依赖的 security 声明让文档页出现 Authorize 按钮（第 5 章已经用上）；模型的 Field description 与 examples（第 2 章）填充字段级说明。全链路的元数据入口在各章都出现过，本文档章是它们的汇流处。
把 JSON 当活契约消费
第一消费方式：客户端代码生成。把 openapi.json 喂给 openapi-typescript、openapi-generator 之类的工具，直接产出前端的 TypeScript 类型与请求函数。前端的请求参数与响应类型从此与后端签名同源，跨语言的契约漂移在编译期暴露。适用判断：前后端分属两个团队、接口数量大（几十个起）、双方愿意把生成物纳入构建流程——三者齐备收益显著；一人全栈的小项目，手写 fetch 加几个类型反而轻快。
第二消费方式：契约测试。CI 里先请求 openapi.json，校验实现与契约的漂移（例如某接口悄悄改了响应模型，快照对比立刻红掉），再用契约驱动 mock 服务给前端提供可联调的假后端。第 5 章测试一节的"契约快照测试"就是这件事的轻量形态，把快照对象从单个接口换成整份规范即得完整版。
第三消费方式：API 网关与工具链集成。网关按 OpenAPI 生成路由配置与校验规则，把非法请求在入口拦下；监控工具按 operation id 聚合延迟与错误率，接口粒度的可观测性不需要人工登记接口清单。
三种消费共享同一个前提：规范是构建产物而不是手工文档——这也划出了边界：OpenAPI 表达不了的东西（调用顺序约束、幂等语义、限流策略）仍然需要人写在 description 里或另立文档，机器契约覆盖结构，人类文档覆盖语义，两者互补而非替代。
文档的安全与开关
docs 与 redoc 默认对公网开放，生产环境的三种处置：内部系统无所谓；对外服务把文档路由藏在鉴权之后（用依赖保护 docs 路径，或仅在网关层放行内网来源）；公开 API 则干脆保留—— Stripe、GitHub 的 API 文档本就是公开资产。要彻底关闭时构造 FastAPI 时传 docs_url=None 与 redoc_url=None，openapi.json 也一并消失。**判断依据是信息披露面**：文档暴露了你的全部接口形状，对攻击者是免费的侦察资料；对开放平台则是降低接入成本的门面。
一个易被忽略的细节：文档页本身也消耗服务资源（每次渲染拉取 JSON 与静态资源），高流量服务把 docs 路径与业务路径的限流策略分开配置是稳妥做法——它与第 4 章静态文件、第 7 章反向代理的讨论同属"哪些东西该由应用进程外的层来服务"这个母题。
图示：声明的汇流与契约的消费
常见疑问两则
**文档里出现了我不想暴露的内部接口怎么办？**优先怀疑依赖与模型的可 reach 性——接口只要注册就会进文档。真正内部的接口应该独立成内部应用或至少加鉴权，靠"从文档隐藏"（include_in_schema=False 可以做到）只是视觉隐藏，路径仍然可访问，不是安全手段，只是文档整洁手段。
**自动文档与手写文档平台（语雀、Confluence）怎么共存？**结构契约交给自动文档，业务语义沉淀在手写平台并链接到 docs 页——两个文档系统的分工与第 4 章"状态码与错误码分层"同构：机器管的归机器，人写的管语义，别让两边做对方更擅长的事。
动手实验：十五分钟看懂文档的生成规则
本章内容可以用一个小实验全部坐实。取第 2 章到第 5 章的任何一个接口，做四次修改，每次改完刷新文档页并请求 openapi.json 对比：
第一次，给某个查询参数加 Query(ge=1, le=50)——文档里该参数出现取值范围说明，JSON 的 schema 里出现数字边界字段。第二次，给请求体模型的某字段加 Field(description="渠道编号")——文档的字段表里出现这行说明。第三次，给路由加 responses={429: {"description": "请求过于频繁"}}——文档的响应区多出 429 条目。第四次，把某接口的 include_in_schema 设为 False——文档里消失，但路由仍然可访问（用客户端直接请求验证）。
四次改动的共同结论：文档是代码的投影，投影规则稳定可测。这个认知的价值在协作中兑现：前端同事问"这个参数的合法范围是什么"，你不必查文档平台，改代码里的约束、文档自动同步；review 接口时看到约束没写进 Query 或 Field，可以直接指出"这个约束没进契约"——文档质量成了代码质量的一部分，评审标准也随之升级。
顺带留意 openapi.json 本身：把它保存下来对比两个版本之间的差异，是检查"这次发布改了哪些接口行为"的最严谨方式——第 5 章提到的契约快照测试，本质就是把这个对比自动化进 CI。
常见问题速答
**问题：接口很多，文档页卡怎么办？**接口过百后交互式文档渲染变慢。三个缓解：用阅读版界面分担浏览场景；标签分组折叠让首屏轻量；终极方案是拆服务——文档卡往往和接口数一起提示该拆服务了，性能问题变成架构信号。
**问题：同一接口不同版本（旧版新版共存）怎么组织？**路径前缀分版本（两个路由器各挂一个前缀），文档用标签区分版本组。比同一接口内兼容多版本清晰得多——版本是接口集合的属性，不是单个接口的参数。
**问题：生成的结构里字段顺序乱了能控吗？**结构按模型字段声明顺序输出，想调整展示顺序就调整模型字段的声明顺序——这个副作用其实很合理：文档顺序跟随代码阅读顺序。必须独立排序的罕见合规需求，用模型配置的生成钩子解决，但先确认值得。
**问题：非 FastAPI 的服务也想统一文档入口怎么办？**聚合层可以做（各服务的规范汇总到一个文档门户），但更常见的是接受每服务一套文档加一个服务目录页——分布式系统的文档边界与服务边界一致，强行统一反而制造耦合。
本节要点回顾
- 同源原理：文档是构建产物，签名、模型、安全声明、元数据四处汇流成 openapi.json，人工维护文档的同步差被结构性消除。
- 可读性三投入：应用级 description 写全局约定、接口 docstring 写业务语义、responses 补错误形态——机器推不出来的信息是人工投入的正确位置。
- 三种消费：代码生成锁前端契约、契约测试锁实现漂移、网关集成换可观测性，前提都是"规范即构建产物"。
- 边界认识：OpenAPI 覆盖结构不覆盖语义，幂等、顺序、限流仍需人类文档补充。
- 安全处置：按信息披露面决定内网、鉴权、公开或关闭；include_in_schema 是整洁手段不是安全手段。
延伸与边界
文档体系的边界在第 6.2 节开头就画过（机器管结构、人管语义），收尾时再补两条实操边界。其一，规范的版本治理：OpenAPI 规范自身也在演进（3.0 与 3.1 的差异会影响生成工具的兼容性），升级生成目标版本前先确认下游工具链支持——契约的价值在于被消费，消费方不认可的升级是负资产。其二，文档的膨胀治理：接口只增不减是文档退化的主因，废弃流程（标注废弃、与消费方确认、定期清除）要像代码清理一样有节奏——一份只有活接口的文档，才配得上"活契约"的名字。
延伸向协作流程的最后一环：把 openapi.json 的变更纳入接口评审（发布说明里附规范差异摘要），前端在差异里认领影响面——当契约变更像代码变更一样可见可追溯时，前后端的接口协作才算真正工业化。这也是本册"代码即契约"主线的终点形态。
- 契约是活资产：规范随代码生长、被工具消费、进发布流程——把文档当资产管理而非负担清偿，是接口团队成熟的标志。
让规范差异进入发布说明的习惯，是这套体系从个人技巧变成团队流程的最后一公里。