企业官网建设流程全解析

1. 项目概述：为什么一个数据科学家要亲手写API文档？

“From Data Science to Production: Generating API Documentation with Swagger”——这个标题乍看像是一篇技术迁移指南，但实际拆开来看，它直击当前数据科学落地中最常被忽视的“最后一公里”痛点：模型上线后，没人知道怎么调用它。我带过十几支数据团队，几乎每支都踩过这个坑：算法工程师把模型封装成Flask服务跑在本地，测试通过就扔给后端同事；后端打开/predict接口，发现请求体是JSON但字段名全靠猜，返回格式里混着{"result": 0.874, "confidence": 0.92, "class_id": "cat"}和{"error": "missing feature 'age' in input"}两种结构；前端调了三天接口，最后发现文档藏在Jupyter Notebook第7页的Markdown单元格里，还写着“待更新”。Swagger不是新工具，但它在数据科学生产化中扮演的角色，远不止“自动生成HTML页面”这么简单——它是数据科学家与工程团队之间的协议契约，是模型从实验环境走向真实业务系统的信用凭证。

核心关键词“Swagger”在这里不是泛指OpenAPI规范，而是特指以代码即文档（Code-as-Document）方式驱动的、可执行的接口契约。它强制要求你在写接口逻辑前，先定义清楚输入数据的schema、输出状态码的语义、错误类型的边界条件。这种“先契约、后实现”的思维，恰恰是数据科学家最缺的工程素养。比如你训练了一个用户流失预测模型，输入需要12个特征字段（其中3个是时间序列聚合值），输出要区分“高风险/中风险/低风险”三类并附带置信度区间。如果只靠口头沟通或Word文档，工程侧很可能漏掉对last_30d_login_count字段做空值填充，或者把risk_level返回成数字编码而非枚举字符串。而Swagger YAML里的一行定义：

components: schemas: PredictionInput: type: object required: [user_id, last_30d_login_count, avg_session_duration_sec] properties: user_id: type: string example: "U-7892" last_30d_login_count: type: integer minimum: 0 example: 5

就锁死了字段名、类型、必填性、取值范围、示例值——这些信息直接生成可交互的API调试界面，后端能据此生成DTO类，前端能据此生成TypeScript接口定义，测试同学能据此编写自动化校验脚本。这不是在增加工作量，而是在把模糊的协作成本，转化成明确的代码契约成本。适合谁来读？如果你是刚把第一个XGBoost模型部署到服务器的数据科学家，正被产品问“这个接口怎么调”，或者你是工程负责人，正为算法团队交付的接口反复返工头疼，这篇就是为你写的。它不讲Swagger语法基础，而是聚焦在数据科学场景下，如何用最小改动让文档真正“活”起来——能跑、能测、能同步、能演进。

2. 核心设计思路：为什么不用Postman导出或手写YAML？

很多团队尝试过“快速方案”：用Postman录制一次成功请求，导出OpenAPI 3.0 JSON；或者让算法同学在Git仓库里维护一个api-spec.yaml文件。这两种方式在数据科学项目中几乎必然失败，原因很具体：它们割裂了文档与代码的生命周期。我见过最典型的反面案例是一家金融科技公司的风控模型API——Postman导出的文档里，/v1/credit_score接口的200响应体定义为：

{ "score": 620, "level": "medium", "reasons": ["high debt ratio", "short credit history"] }

但实际代码里，当用户信用分低于500时，后端会返回403 Forbidden并附带{"error": "application_rejected", "code": "CREDIT_TOO_LOW"}。因为Postman只录了“正常流程”，而异常分支根本没覆盖。更麻烦的是，当算法同学优化模型，把reasons字段从字符串数组改成结构化对象（含category和weight子字段）时，Postman文档不会自动更新，工程侧还在用旧结构解析，导致JSON解析异常崩溃。

手写YAML的问题更隐蔽：它把文档变成了静态资产。假设你的模型服务基于FastAPI开发，而FastAPI原生支持OpenAPI规范生成。如果你手动维护YAML，就必须在每次修改@app.post("/predict")的参数注解（如把feature_a: float改成feature_a: Optional[float] = None）后，同步去改YAML里的components.schemas.PredictionInput.properties.feature_a.type。这违背了“单一事实源”原则——当代码和文档不一致时，以谁为准？答案往往是“以代码为准”，但文档已失效，新来的同事只能靠读代码猜逻辑。

因此，本项目的核心设计思路是：让Swagger文档成为代码的衍生物，而非独立产物。具体路径有两条，我们最终选择第二条，因为它对数据科学家最友好：

1. 完全代码优先（Code-First）：用FastAPI的Pydantic模型定义输入输出，框架自动注入OpenAPI元数据，再通过app.openapi()方法导出JSON/YAML。优点是零维护成本，缺点是文档深度依赖框架能力，比如无法精细控制某个字段的描述文本位置。
2. 混合模式（Hybrid）：用Pydantic定义核心数据模型（保证类型安全），但将OpenAPI文档的顶层结构（如info、servers、tags）和关键扩展字段（如x-code-samples、x-logo）单独维护在一个YAML文件中，再通过工具合并。这种方式既保留了代码即文档的可靠性，又给了数据科学家定制文档呈现的自由度。

我们选混合模式，因为数据科学API常需特殊说明：比如模型版本号要显示在文档标题栏，不同环境（staging/prod）的base URL要清晰标注，某个字段的业务含义需要用非技术语言解释（如"income_bracket"不是“年收入分段”，而是“按央行征信标准划分的五级收入区间”）。这些信息硬塞进Pydantic模型注释里会污染代码，而放在独立YAML中，配合CI/CD流程自动注入版本号，才是可持续方案。关键在于，所有与模型逻辑强相关的部分（字段名、类型、必填性、示例值）必须来自代码，所有与用户体验相关的部分（UI展示、多环境配置、业务说明）可来自YAML。这种分工让数据科学家专注模型逻辑，工程同学把控文档体验，各司其职。

3. 实操细节拆解：从FastAPI代码到可交付文档的完整链路

3.1 数据模型定义：用Pydantic构建可验证的契约骨架

数据科学API的文档质量，80%取决于输入输出模型的定义精度。我们不用dict或Any这种宽泛类型，而是为每个接口创建专用的Pydantic模型。以用户流失预测为例，创建models.py：

from pydantic import BaseModel, Field, validator from typing import List, Optional, Dict, Any from datetime import datetime class PredictionInput(BaseModel): """ 用户流失风险预测的输入数据结构。 所有字段均为业务系统提供，无需算法侧预处理。 """ user_id: str = Field(..., description="用户唯一标识符，格式为U-{数字}", example="U-12345") signup_date: str = Field(..., description="用户注册日期，ISO格式", example="2022-03-15") last_login_days_ago: int = Field( ..., ge=0, le=365, description="距今最近一次登录的天数，0表示今日登录", example=2 ) avg_session_duration_sec: float = Field( ..., ge=0.0, le=7200.0, description="过去30天平均单次会话时长（秒）", example=124.5 ) # 注意：这里不定义模型内部特征（如PCA降维后的向量）， # 因为那是算法实现细节，不应暴露给调用方 @validator('signup_date') def validate_signup_date(cls, v): try: datetime.fromisoformat(v) except ValueError: raise ValueError("signup_date must be in ISO format (YYYY-MM-DD)") return v class PredictionOutput(BaseModel): """ 预测结果结构，包含风险等级、置信度及可解释性信息。 """ user_id: str risk_level: str = Field( ..., description="风险等级，取值为 'low' | 'medium' | 'high'", example="high" ) confidence_interval: List[float] = Field( ..., min_items=2, max_items=2, description="95%置信区间，格式为[lower_bound, upper_bound]", example=[0.72, 0.89] ) explanation: Dict[str, Any] = Field( ..., description="模型决策依据，键为影响因子名称，值为归因权重", example={"login_frequency_drop": 0.42, "session_duration_decline": 0.38} )

这段代码的关键细节远超表面：

• Field(..., description=...)中的description会被FastAPI自动提取到OpenAPI文档的schema.description字段，这是业务语义注入点。比如last_login_days_ago的描述明确写了“0表示今日登录”，这比代码注释更能防止调用方误解。
• ge/le等约束不仅用于运行时校验，还会生成OpenAPI的minimum/maximum，让Swagger UI自动校验输入值范围。
• @validator装饰器定义的日期校验，会在请求解析阶段抛出标准HTTP 422错误，并附带清晰的错误消息（如"detail": [{"loc": ["body", "signup_date"], "msg": "signup_date must be in ISO format (YYYY-MM-DD)", "type": "value_error"}]），这个错误结构也会被纳入OpenAPI的422响应定义中。
• 特别注意注释：“这里不定义模型内部特征……不应暴露给调用方”。这是数据科学API设计铁律——调用方只需提供原始业务字段（如last_login_days_ago），模型服务内部负责特征工程（如计算滑动窗口统计量）。如果把PCA向量作为输入字段，等于把算法实现细节耦合进API契约，一旦模型重构，整个接口就崩了。

3.2 FastAPI接口实现：让路由成为文档的天然锚点

定义好模型后，接口实现要严格绑定模型。在main.py中：

from fastapi import FastAPI, HTTPException, status from models import PredictionInput, PredictionOutput import joblib import numpy as np # 加载预训练模型（实际项目中应使用模型注册中心） model = joblib.load("models/churn_predictor_v2.1.pkl") app = FastAPI( title="用户流失风险预测API", description="基于XGBoost的实时用户流失风险评估服务，支持批量预测", version="2.1.0", # 这个版本号会出现在Swagger UI顶部 contact={ "name": "数据科学平台组", "email": "ds-platform@company.com" }, servers=[ {"url": "https://api-staging.company.com/v1", "description": "Staging环境"}, {"url": "https://api-prod.company.com/v1", "description": "生产环境"} ] ) @app.post( "/predict", response_model=PredictionOutput, summary="执行单用户流失风险预测", description="根据用户历史行为数据，返回流失风险等级及置信区间。" "注意：此接口仅接受单个用户请求，批量预测请使用/predict/batch。", tags=["预测服务"], responses={ 200: { "description": "预测成功，返回风险等级和置信区间", "content": { "application/json": { "example": { "user_id": "U-12345", "risk_level": "high", "confidence_interval": [0.72, 0.89], "explanation": {"login_frequency_drop": 0.42} } } } }, 422: { "description": "输入数据校验失败，请检查字段类型和范围", "content": { "application/json": { "example": { "detail": [ { "loc": ["body", "last_login_days_ago"], "msg": "ensure this value is greater than or equal to 0", "type": "value_error.number.not_ge" } ] } } } } } ) async def predict_single(input_data: PredictionInput) -> PredictionOutput: try: # 特征工程：将业务字段转换为模型所需特征向量 features = [ input_data.last_login_days_ago, input_data.avg_session_duration_sec, # ... 其他10个字段的转换逻辑 ] # 模型预测 pred_proba = model.predict_proba([features])[0] risk_level = ["low", "medium", "high"][np.argmax(pred_proba)] confidence = np.max(pred_proba) # 构造输出（此处简化，实际需计算置信区间） return PredictionOutput( user_id=input_data.user_id, risk_level=risk_level, confidence_interval=[confidence - 0.05, confidence + 0.05], explanation={"dummy_explanation": 1.0} ) except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"模型预测失败: {str(e)}" ) # 批量预测接口（演示不同响应结构） @app.post( "/predict/batch", response_model=List[PredictionOutput], summary="执行批量用户流失风险预测", tags=["预测服务"] ) async def predict_batch(input_list: List[PredictionInput]) -> List[PredictionOutput]: # 实现略 pass

这里的关键实操技巧：

• response_model=PredictionOutput不只是类型提示，它强制FastAPI在返回前校验输出结构。如果代码里返回了{"user_id": "U-12345", "risk": "high"}（字段名错为risk而非risk_level），FastAPI会自动抛出500错误并记录日志，而不是让错误数据流到下游。这个校验过程会生成精确的OpenAPI响应schema。
• responses参数显式定义了200和422的详细结构，包括example值。这些example会直接渲染在Swagger UI的“Try it out”面板中，调用方点一下就能看到标准请求体和响应体，极大降低试错成本。
• tags=["预测服务"]将接口分组，Swagger UI会按tag生成导航菜单，避免几十个接口挤在一页。数据科学API常有“模型管理”、“数据探查”、“预测服务”等不同功能域，合理分组是专业性的体现。
• servers列表定义了多环境URL，Swagger UI右上角会自动生成环境切换下拉框。当测试同学在staging环境调试时，所有“Execute”请求都会自动发往staging URL，无需手动改地址——这是减少人为错误的微小但关键的设计。

3.3 文档增强：用独立YAML注入业务上下文

FastAPI生成的基础文档缺少业务层信息。我们创建docs/openapi-extensions.yaml来补充：

# openapi-extensions.yaml info: x-logo: url: "/static/logo-ds.png" altText: "Data Science Platform" x-contact-url: "https://confluence.company.com/ds-api-docs" x-model-version: "2.1.0" # 与FastAPI的version字段联动 x-deployment-status: "production-ready" # 为特定路径添加扩展信息 paths: /predict: post: x-code-samples: - lang: "Python" source: | import requests url = "https://api-prod.company.com/v1/predict" payload = { "user_id": "U-12345", "signup_date": "2022-03-15", "last_login_days_ago": 2, "avg_session_duration_sec": 124.5 } headers = {"Authorization": "Bearer <your-token>"} response = requests.post(url, json=payload, headers=headers) print(response.json()) - lang: "curl" source: | curl -X 'POST' \ 'https://api-prod.company.com/v1/predict' \ -H 'Authorization: Bearer <your-token>' \ -H 'Content-Type: application/json' \ -d '{ "user_id": "U-12345", "signup_date": "2022-03-15", "last_login_days_ago": 2, "avg_session_duration_sec": 124.5 }' x-rate-limit: limit: 100 period: "1 minute" description: "每分钟最多100次调用，超出返回429" /predict/batch: post: x-batch-size-recommendation: "建议单次请求不超过1000条记录" x-processing-time: "平均响应时间<200ms（P95）"

这个YAML不参与API运行，只用于增强文档。关键点在于：

• x-*开头的字段是OpenAPI的扩展机制，Swagger UI会忽略它们，但我们的文档生成工具（见下节）会读取并注入到最终HTML中。
• x-code-samples提供了开箱即用的调用示例，覆盖Python和curl两种最常用方式。示例中的<your-token>占位符会触发Swagger UI的认证弹窗，引导用户配置token。
• x-rate-limit和x-processing-time这类信息，是运维同学最关心的SLA指标，但不适合写在代码注释里。独立YAML让SRE团队能自主维护这些运营参数。
• x-model-version与FastAPI的version字段保持一致，我们在CI流程中用脚本自动同步，确保文档版本号与实际部署模型版本严格对应——这是审计合规的关键证据。

4. 文档生成与发布：从代码到可交互页面的自动化流水线

4.1 工具链选型：为什么选swagger-ui-dist而非Redoc？

市面上主流的OpenAPI渲染器有Swagger UI、Redoc、RapiDoc。我们最终选择Swagger UI（通过swagger-ui-dist包集成），原因非常务实：

• 调试能力不可替代：Swagger UI的“Try it out”功能允许调用方直接在浏览器里构造请求、设置Header、查看原始响应Body和Status Code。Redoc虽然UI更简洁，但默认禁用执行功能，需额外配置CORS和代理，而数据科学API常部署在内网，调试代理配置复杂度远超收益。
• 错误反馈最直观：当输入last_login_days_ago: -5触发Pydantic校验时，Swagger UI会高亮显示该字段的错误消息，并在右侧Response面板中展示完整的422错误JSON。Redoc的错误提示分散在不同区域，新手难以关联。
• 企业级定制成熟：Swagger UI支持通过presets和plugins深度定制。比如我们添加了plugin-topbar插件，在顶部状态栏显示模型版本号和环境标签（staging/prod），这个功能Redoc原生不支持，需魔改源码。

安装与集成极其简单：

pip install fastapi uvicorn swagger-ui-dist

在FastAPI应用中，我们不使用app.docs_url（默认的/docs），而是自定义一个路由来托管Swagger UI：

# main.py 续 from fastapi.staticfiles import StaticFiles from starlette.responses import HTMLResponse import os # 挂载静态文件（存放自定义CSS/JS） app.mount("/static", StaticFiles(directory="static"), name="static") @app.get("/apidocs", include_in_schema=False) async def custom_swagger_ui_html(): # 读取基础HTML模板 with open("templates/swagger-ui.html") as f: html_content = f.read() # 注入动态参数：API文档URL、标题、Logo路径 html_content = html_content.replace( "{{OPENAPI_URL}}", "/openapi.json" ).replace( "{{PAGE_TITLE}}", "用户流失预测API文档 v2.1.0" ).replace( "{{LOGO_PATH}}", "/static/logo-ds.png" ) return HTMLResponse(content=html_content, status_code=200)

templates/swagger-ui.html是一个精简版的Swagger UI加载页，核心是这段JavaScript：

<script> window.onload = function() { // 初始化Swagger UI const ui = SwaggerUIBundle({ url: "{{OPENAPI_URL}}", dom_id: '#swagger-ui', presets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.presets.standaloneLayout ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl, // 自定义插件：顶部状态栏 function TopBarPlugin() { return { statePlugins: { topbar: { wrapActions: { updateTopbar: (oriAction, system) => (topbarState) => { const env = window.location.hostname.includes('staging') ? 'STAGING' : 'PROD'; const version = "{{PAGE_TITLE}}".match(/v(\d+\.\d+\.\d+)/)?.[1] || 'unknown'; return oriAction({ ...topbarState, title: `{{PAGE_TITLE}} | ${env} | v${version}` }); } } } } }; } ], layout: "StandaloneLayout" }); window.ui = ui; }; </script>

这个方案的优势在于：所有定制化逻辑都在前端JavaScript中，不侵入FastAPI后端代码。当UI设计师要调整配色或添加新功能时，只需改HTML和JS，无需重启Python服务。我们甚至把swagger-ui.html放在Git仓库的/docs目录下，由CI流程自动部署到CDN，实现文档UI的灰度发布。

4.2 OpenAPI规范生成：合并代码与YAML的自动化脚本

FastAPI的app.openapi()方法只能生成基础JSON，我们需要将openapi-extensions.yaml中的扩展字段合并进去。为此编写scripts/generate-openapi.py：

#!/usr/bin/env python3 """ 生成最终OpenAPI规范的脚本。 步骤：1. 从FastAPI应用获取基础OpenAPI JSON 2. 加载openapi-extensions.yaml 3. 深度合并（递归覆盖，不删除原字段） 4. 写入dist/openapi.json """ import json import sys from pathlib import Path import yaml from deepmerge import always_merger # pip install deepmerge # 导入FastAPI应用（注意：不能直接import main，会触发uvicorn启动） sys.path.insert(0, str(Path(__file__).parent.parent)) from main import app # noqa def load_yaml(file_path: str) -> dict: with open(file_path, 'r', encoding='utf-8') as f: return yaml.safe_load(f) def merge_openapi(base: dict, extensions: dict) -> dict: """深度合并OpenAPI规范，优先使用extensions中的值""" # 复制基础规范，避免修改原对象 result = json.loads(json.dumps(base)) # 合并顶层字段（info, paths, components等） for key in ['info', 'paths', 'components', 'security']: if key in extensions: if key not in result: result[key] = {} always_merger.merge(result[key], extensions[key]) # 特殊处理：servers列表应合并而非覆盖（保留FastAPI定义的server，再加extensions里的） if 'servers' in extensions and 'servers' in result: result['servers'] = result['servers'] + extensions['servers'] return result def main(): # 步骤1：获取FastAPI生成的OpenAPI openapi_spec = app.openapi() # 步骤2：加载扩展YAML extensions_path = Path(__file__).parent.parent / "docs" / "openapi-extensions.yaml" if not extensions_path.exists(): print(f"警告：未找到扩展文件 {extensions_path}，仅使用FastAPI生成的规范") extensions = {} else: extensions = load_yaml(extensions_path) # 步骤3：合并 final_spec = merge_openapi(openapi_spec, extensions) # 步骤4：写入dist目录 dist_dir = Path(__file__).parent.parent / "dist" dist_dir.mkdir(exist_ok=True) output_path = dist_dir / "openapi.json" with open(output_path, 'w', encoding='utf-8') as f: json.dump(final_spec, f, indent=2, ensure_ascii=False) print(f"✅ OpenAPI规范已生成：{output_path}") print(f" 接口总数：{len(final_spec.get('paths', {}))}") print(f" 模型定义数：{len(final_spec.get('components', {}).get('schemas', {}))}") if __name__ == "__main__": main()

这个脚本的关键设计：

• 使用deepmerge.always_merger进行深度合并，确保paths./predict.post.x-code-samples这样的嵌套字段能正确覆盖，而不是简单替换整个paths对象。
• 对servers字段做特殊处理：FastAPI已定义staging/prod URL，extensions YAML中可能添加localhost用于本地调试，合并时应追加而非覆盖。
• 输出到dist/openapi.json，这个路径与前面swagger-ui.html中{{OPENAPI_URL}}的值一致，形成闭环。

在CI/CD流程中，这个脚本是发布前的必检步骤：

# .github/workflows/deploy.yml - name: Generate OpenAPI Spec run: python scripts/generate-openapi.py - name: Validate OpenAPI Spec run: | npm install -g openapi-validator openapi-validator dist/openapi.json - name: Deploy Docs run: | cp dist/openapi.json docs/ # 同步static/和templates/到文档站点

4.3 文档发布与版本管理：让每次模型更新都留下可追溯的文档快照

文档不是发布一次就完事，它必须与模型版本严格绑定。我们采用“文档即制品”策略：

• 每次模型训练完成，CI流程会：
  1. 将模型文件（.pkl）上传至对象存储，路径为models/churn_predictor_v2.1.0.pkl；
  2. 运行generate-openapi.py生成dist/openapi_v2.1.0.json；
  3. 将openapi_v2.1.0.json和swagger-ui.html打包成ZIP，上传至文档仓库。

这样，https://docs.company.com/churn-api/v2.1.0/就是一个永久可用的文档快照。当某次线上事故需要回溯时，运维可以精确查看“当时部署的v2.1.0版本，其/predict接口是否定义了429响应码”，而不是翻Git历史猜。

更进一步，我们在Swagger UI中添加了版本切换功能。修改swagger-ui.html，在顶部添加下拉菜单：

<select id="version-selector" onchange="switchVersion(this.value)"> <option value="v2.1.0">v2.1.0 (当前)</option> <option value="v2.0.0">v2.0.0</option> <option value="v1.5.0">v1.5.0</option> </select> <script> function switchVersion(version) { const newUrl = `/docs/${version}/openapi.json`; window.ui.specActions.updateUrl(newUrl); } </script>

后端路由/docs/{version}/openapi.json会根据version参数返回对应ZIP包中的openapi_{version}.json。这个设计让数据科学家、测试、产品都能在同一页面对比不同版本的接口差异，比如v2.1.0新增了explanation字段，而v2.0.0没有——这种对比在代码diff中很难一眼看出，但在Swagger UI中点击切换即可。

5. 常见问题与实战排查：那些只有踩过坑才知道的细节

5.1 问题速查表：高频故障与根因分析

5.2 实操心得：那些文档里不会写的血泪经验

心得一：永远不要在文档中写“详见代码注释”
我曾接手一个贷款审批模型API，文档里有一句：“输入字段含义详见models.py第42行注释”。结果那行注释是# TODO: add business logic here。数据科学家习惯用TODO标记未完成项，但文档一旦发布，这个TODO就成了永久谜题。解决方案：所有业务语义必须显式写在Field(description=...)中，且描述要完整句子（如“用户近30天登录次数，用于计算活跃度衰减系数”），而非缩写或代词（如“登录次数”）。

心得二：example值必须是真实可运行的
早期我们为user_id字段设example="U-12345"，但实际生产环境ID格式是USR-2023-XXXXXX。测试同学用示例值调试成功，上线后用真实ID调用却失败，因为正则校验不匹配。现在规则是：所有example值必须来自生产环境脱敏样本库，每周自动更新。我们甚至写了个小脚本，从生产日志中随机采样100个真实user_id，取第一个作为example。

心得三：错误响应文档比成功响应更重要
90%的API问题出在错误处理。我们强制要求每个接口的responses中，4xx和5xx响应必须有content定义。例如400 Bad Request不能只写{"detail": "invalid input"}，而要明确：

400: { "description": "输入数据格式错误，如JSON解析失败或字段类型不匹配", "content": { "application/json": { "example": { "detail": "Invalid JSON: Expecting property name enclosed in double quotes" } } } }

这样，前端同学看到400错误时，能立刻判断是自己发错了JSON，还是后端服务有问题，而不是盲目重试。

心得四：文档的“最后更新时间”必须自动化
我们曾在info.description中手写“最后更新：2023-10-15”。结果模型迭代了三次，文档没更新，产品按旧文档对接，发现risk_level字段从字符串变成了整数。现在，generate-openapi.py脚本会在info中自动注入：

"info": { "x-last-updated": datetime.now().isoformat(), "x-generated-by": "fastapi-swagger-generator v1.2.0" }

这个时间戳会显示在Swagger UI底部，成为文档可信度的硬指标。

心得五：给非技术人员准备“文档阅读指南”
Swagger UI对工程师很友好，但对产品经理、业务方来说仍是黑盒。我们在文档首页顶部添加了一个折叠面板：

<details> <summary>📌 新