最省力的示例代码生成方式是用 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-generatorv6+ 默认启用 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_datafixture - 测试函数签名写成
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} 和真实值区分开，后续维护成本越低。 
