用途
该技能是使用 Speakeasy 生成 SDK、Terraform Provider 与 MCP 服务器时的最佳实践集合,覆盖完整生命周期:OpenAPI 规范准备、代码优先提取、生成工作流、各语言指南、定制与测试。
适用场景包括:从 OpenAPI 规范生成 SDK、Terraform Provider 或 MCP 服务器;从现有代码提取 OpenAPI 规范;定制 SDK 生成(hooks、认证、错误处理、重试、分页);修复 OpenAPI 校验错误或应用 overlay;测试生成的 SDK;了解各语言 SDK 模式;升级或调整 workflow.yaml 中的 Speakeasy CLI 版本;在规范或版本变更后重新生成 SDK;定制 SDK README 文档;通过 overlay 为 OpenAPI 规范添加示例;测试生成的 SDK 端点。
主要能力与组织方式
技能内容位于相对于本文件的 content/ 子目录中,应读取与任务对应的具体指南,而非仅凭索引作答。指南也可通过 Speakeasy CLI 访问:speakeasy agent context [path]。
目录结构覆盖:
- plans/:sdk-generation.md(完整 SDK 生成工作流)、tf-provider-generation.md
- code-first/:fastapi、flask、django、spring-boot、nestjs、hono、rails、laravel
- spec-first/:validation、overlays(含 overlay recipes、多 overlay 工作流、元数据跟踪、自定义安全方案)、security-schemes、pagination、schemas
- sdk-languages/:python、typescript、go、java、csharp、ruby、php
- sdk-customization/:hooks、runtime-configuration、authentication-config、error-handling、custom-code、multi-target-sdks、multi-repo-workflows、mcp-server、readme-customization
- sdk-testing/:integration-testing、arazzo-testing、contract-testing
- terraform/:crud-mapping、customization、testing-guide、publishing
- CLI_REFERENCE.md:CLI 命令文档
技能提供快速路由表与决策树帮助定位入口:先判断是否已有 OpenAPI/Swagger 规范,再判断规范是否有效,进而选择生成 SDK 还是 Terraform Provider;若无规范但有 API 代码,则按框架路由到对应 code-first 指南。
使用方式
常见工作流:
工作流 A:首次生成 SDK
- 阅读 content/plans/sdk-generation.md
- 运行
speakeasy quickstart --skip-interactive --output console -s spec.yaml -t python -o ./sdk - SDK 生成在输出目录
工作流 B:现有代码转 SDK
- 在 content/code-first/ 中识别框架
- 提取 OpenAPI 规范
- 运行
speakeasy lint openapi --non-interactive -s spec.yaml校验 - 使用 content/spec-first/ 指南修复问题
- 按 content/plans/sdk-generation.md 生成 SDK
工作流 C:SDK 定制
- 确保 gen.yaml 存在
- 阅读 content/sdk-customization/ 指南
- 修改 gen.yaml
- 运行
speakeasy run -y --output console重新生成
工作流 D:多目标 SDK
- 阅读 content/sdk-customization/multi-target-sdks.md
- 在 workflow.yaml 配置多个 sources
- 设置 target 输出到 packages/ 子目录
- 为每个 target 创建 CI 工作流
工作流 E:SDK 扩展
- 需持久化任意位置的改动:content/sdk-customization/custom-code.md
- 横切关注点:content/sdk-customization/hooks.md
- 预定义扩展点:content/sdk-languages/typescript.md#custom-code-regions
- 复杂逻辑:content/sdk-languages/typescript.md#extra-modules-pattern
工作流 F:升级与重新生成
- 查看 .speakeasy/workflow.yaml 中的 speakeasyVersion
- 更新 speakeasyVersion
- 运行
speakeasy run重新生成 - 测试生成的 SDK
- 提交变更
核心 CLI 命令:
speakeasy quickstart --skip-interactive --output console -s spec.yaml -t python -o ./sdk:非交互式 SDK 初始化speakeasy run -y --output console:根据 gen.yaml 重新生成 SDKspeakeasy lint openapi --non-interactive -s spec.yaml:校验 OpenAPI 规范speakeasy auth login:登录 Speakeasy
处理大型 OpenAPI 文档时,建议不将完整规范载入上下文,而使用 yq/jq 提取所需片段,例如 yq '.paths | keys' spec.yaml、yq '.components.schemas.User' spec.yaml 等;若无 yq/jq 可用,则使用定向 grep。
适用场景与限制
该技能适用于需要生成或定制 SDK、Terraform Provider、MCP 服务器的开发工作流,以及围绕 OpenAPI 规范进行校验、overlay、测试与故障排查的场景。其提供故障排查树,覆盖 ResponseValidationError、SDK 与实时 API 行为不一致、类型不匹配、枚举值未识别等问题,并指向对应的 contract-testing、validation、overlays 指南。缺少 OpenAPI 规范且无 API 代码时无法继续。文档内容涉及的功能、支持范围、平台与发布渠道以各指南实际描述为准;本简介未提供的收费、价格、效果等信息暂未提供。