如何在测试中自动生成API的示例代码段

最省力的示例代码生成方式是用 openapi-generator 从 openapi spec 直接生成：先用 html2 验证 spec 合法性，再按需选 python/postman 等模板输出可执行片段，配合 pytest 参数化、httpx+pydantic 运行时组装及 curl 安全转义，确保示例真实、隔离、易维护。

用 openapi-generator 从 OpenAPI Spec 直接生成示例代码

如果你已有符合规范的 openapi.yaml 或 swagger.json，这是最省力、可复现的方式。它不依赖运行时，也不需要手写 mock 逻辑。

常见错误是直接跑默认命令却没指定语言或模板，结果输出一堆 Java 文件——其实你只想要 Python 的 requests 示例片段。

• 用 openapi-generator generate -i openapi.yaml -g html2 先验证 spec 是否合法（html2 模板能快速暴露格式问题）
• 生成纯调用示例：用 -g python + --additional-properties=generateSourceCodeOnly=false,hideGenerationTimestamp=true，再删掉模型类和 client 初始化部分，只留 api_instance.xxx_with_http_info(...) 调用块
• 若要更轻量的 curl 或 requests 片段，优先选 -g postman 导出 Collection，再用脚本抽取出 request.url、request.method 和 request.body 字段
• 注意 openapi-generator v6+ 默认启用 strict mode，遇到 x-example 缺失的字段会跳过示例生成；加 --strict-spec=false 可绕过（但建议补全 spec）

在 Pytest 中用 pytest_generate_tests 动态注入参数化示例

适合已有测试骨架、想把 API 示例当数据驱动用的场景。不是生成文档，而是让每个示例变成一个独立 test case。

容易踩的坑是把示例硬编码进 params 列表里，导致 spec 更新后测试失效。

• 把示例统一放在 tests/examples/ 下，按 {endpoint}_{method}.json 命名，内容含 url、method、headers、body、expected_status
• 在 conftest.py 里用 pytest_generate_tests 扫描该目录，用 metafunc.parametrize 注入 example_data fixture
• 测试函数签名写成 def test_api_example(example_data):，内部用 requests.request(**example_data) 发起调用
• 别在 example_data 里塞真实敏感值（如 Token），用占位符如 {auth_token}，启动测试前用环境变量替换

用 httpx + pydantic 在运行时拼接可执行示例

当 API 尚未稳定、spec 经常变，又需要开发者立刻看到“这段代码真能跑”，就得在测试里现场组装请求样例。

性能上几乎无影响，但要注意 pydantic 模型的 model_dump() 默认不包含 None 字段，而有些 API 要求显式传 NULL。

• 定义请求模型继承 BaseModel，字段加 examples 参数，如 user_id: int = Field(..., examples=[123])
• 用 model_construct() + model_dump(exclude_unset=True) 生成最小有效 payload
• 发请求前用 httpx.Request(method, url, json=payload).prepare().content 提取原始字节，方便断言或日志输出
• 如果 endpoint 有 path param（如 /users/{id}），别手动字符串格式化，用 str(url).format(id=123) 更安全

curl 示例生成器容易忽略的 Content-Type 和编码细节

很多工具生成的 curl 命令看着对，一粘贴就 400，八成是 -H "Content-Type: application/json" 没加，或者 JSON 里中文被转义错乱。

OpenAPI spec 里的 example 是 raw String，但 curl 命令里必须是 shell-safe 的字符串。

• 用 json.dumps(obj, ensure_ascii=False, separators=(',', ':')) 生成紧凑 JSON，再用 shlex.quote() 包裹，避免空格和单引号破坏命令结构
• GET 请求带 query 参数时，别用 -d，改用 -G --data-urlencode；否则参数会被当成 body 发送
• 上传文件示例不能只写 -F "file=@/path/to/file"，得补上 -H "Content-Type: multipart/form-data" —— 实际 curl 会自动设，但别人复制时容易漏掉注释说明
• 如果 API 要求 Bearer token，示例里写 -H "Authorization: Bearer {token}"，而不是填死值；并在文档顶部注明 token 来源

生成示例代码不是拼凑语法，关键在三点：是否反映真实调用链路、是否隔离了环境依赖、是否让使用者一眼看出哪部分要替换成自己的值。越早把 {placeholder} 和真实值区分开，后续维护成本越低。