用途:当已有 API 代码但缺少 OpenAPI 规范时,从代码中提取规范,以便后续生成 SDK。适用于用户提到“extract OpenAPI”“code first”“generate spec from code”或指定上述框架的场景。
主要能力:按框架提供提取方法。FastAPI 用内置导出(python -c "import json; from myapp import app; print(json.dumps(app.openapi()))" > openapi.json);Flask 用 flask openapi write openapi.json;Django REST Framework 用 python manage.py spectacular --file openapi.yaml;Spring Boot 启动后 curl http://localhost:8080/v3/api-docs -o openapi.json;NestJS 启动后 curl http://localhost:3000/api-json -o openapi.json;Hono 用 zod-openapi 程序化导出;Rails 用 rails rswag:specs:swaggerize;Laravel 用 php artisan l5-swagger:generate。
使用方式:先确认框架与项目路径,选择对应提取命令,输出 openapi.json 或 openapi.yaml。提取后必须校验:speakeasy lint openapi --non-interactive -s openapi.json。如需修复,用 overlay 而非直接改规范:speakeasy overlay apply -s openapi.json -o fixes.yaml。随后可生成 SDK:speakeasy quickstart --skip-interactive --output console -s openapi.json -t <target> -n <name> -p <package>。
限制与注意:项目需可构建且依赖已安装;运行时提取的框架需可导入或启动。不要手写规范、不要直接编辑提取结果、不要跳过校验、不要假设规范完整(可能缺认证、错误响应或请求头)。常见问题包括缺少 operationId、描述、响应 schema、认证信息,或 operationId 重复。缺失事实暂未提供。