sdk-tf-generation-best-practices

Comprehensive best-practices reference for generating SDKs and Terraform providers with Speakeasy. Covers the full lifecycle: OpenAPI spec preparation, code-first extraction, generation workflows, language-specific guides, customization, and testing.

When to Use

• Generating an SDK from an OpenAPI spec

• Generating a Terraform provider from an OpenAPI spec

• Generating an MCP server from an OpenAPI spec

• Extracting an OpenAPI spec from existing code (FastAPI, Flask, Django, Spring Boot, NestJS, Hono, Rails, Laravel)

• Customizing SDK generation (hooks, auth, error handling, retries, pagination)

• Fixing OpenAPI validation errors or applying overlays

• Testing generated SDKs (integration, contract, Arazzo)

• Understanding language-specific SDK patterns (TypeScript, Python, Go, Java, C#, Ruby, PHP)

• Upgrading or bumping the Speakeasy CLI version in workflow.yaml

• Regenerating an SDK after spec or version changes

• Customizing SDK README documentation

• Adding examples to an OpenAPI spec via overlays

• Testing generated SDK endpoints

• User says: "generate SDK", "regenerate SDK", "update SDK", "SDK best practices", "terraform provider", "generate MCP server", "SDK customization", "SDK testing", "test my SDK", "upgrade speakeasy", "bump version", "SDK readme", "SDK documentation", "add examples to spec"

How to Use

This skill contains detailed guides in the content/ subdirectory relative to this file. Read the specific guide for the user's task rather than trying to answer from this index alone.

These guides are also accessible via the Speakeasy CLI:

speakeasy agent context [path]

To find the right guide, use the routing table below or the decision tree.

Quick Routing Table

What are you trying to do?

Goal Start Here

Generate an SDK from an OpenAPI spec content/plans/sdk-generation.md

Generate a Terraform provider content/plans/tf-provider-generation.md

Extract OpenAPI from existing code content/code-first/[framework].md

Fix OpenAPI validation errors content/spec-first/validation.md

Customize SDK generation content/sdk-customization/

Generate multiple SDK variants (Azure, GCP, etc.) content/sdk-customization/multi-target-sdks.md

Set up a multi-SDK monorepo content/plans/sdk-generation.md#advanced-multi-sdk-monorepos

Use overlay recipes (open enums, global headers) content/spec-first/overlays.md#overlay-recipes

Use multi-overlay workflows content/spec-first/overlays.md#multi-overlay-workflow-patterns

Track overlay changes with metadata content/spec-first/overlays.md#overlay-metadata-tracking

Implement custom security (HMAC, signatures) content/spec-first/overlays.md#custom-security-schemes-via-overlay

Add SDK hooks (user-agent, telemetry) content/sdk-customization/hooks.md

Implement HTTP signature authentication content/sdk-customization/hooks.md#custom-security-hook-http-signature-authentication

Configure SDK retries, timeouts, pagination content/sdk-customization/runtime-configuration.md

Configure SDK authentication and security content/sdk-customization/authentication-config.md

Customize SDK error handling content/sdk-customization/error-handling.md

Persist custom code changes across regenerations content/sdk-customization/custom-code.md

Generate MCP server for AI assistants content/sdk-customization/mcp-server.md

Orchestrate multi-repo SDK generation content/sdk-customization/multi-repo-workflows.md

Understand SDK language specifics content/sdk-languages/[language].md

Add custom utilities to Python SDKs content/sdk-languages/python.md#extending-the-sdk-with-sidecar-utilities

Publish Java SDK to Maven Central content/sdk-languages/java.md#maven-central-publishing

Add custom code to TypeScript SDKs content/sdk-languages/typescript.md#custom-code-regions

Publish TypeScript SDK to JSR (Deno) content/sdk-languages/typescript.md#jsr-deno-publishing

Configure Ruby SDK with Sorbet typing content/sdk-languages/ruby.md#sorbet-type-checking

Publish Ruby SDK to RubyGems content/sdk-languages/ruby.md#rubygems-publishing

Configure PHP SDK with Laravel integration content/sdk-languages/php.md#laravel-integration

Publish PHP SDK to Packagist content/sdk-languages/php.md#publishing-to-packagist

Generate Go SDK with interfaces for testing content/sdk-languages/go.md#interface-generation

Use Go SDK in Kubernetes operators content/sdk-languages/go.md#kubernetes-operator-integration

Set up SDK integration tests content/sdk-testing/integration-testing.md

Configure Arazzo API testing content/sdk-testing/arazzo-testing.md

Disable tests for specific endpoints content/sdk-testing/arazzo-testing.md#disabling-tests-via-overlay

Run AI-powered contract tests content/sdk-testing/contract-testing.md

Fix ResponseValidationError at runtime content/sdk-testing/contract-testing.md

Validate spec matches live API content/spec-first/validation.md#dynamic-validation-contract-testing

Upgrade Speakeasy version in workflow.yaml content/plans/sdk-generation.md#version-management

Bump pinned speakeasyVersion to latest content/plans/sdk-generation.md#version-management

Regenerate SDK after spec or version change content/plans/sdk-generation.md

Customize SDK README with documentation content/sdk-customization/readme-customization.md

Add branding, examples, or guides to SDK README content/sdk-customization/readme-customization.md

Add examples to OpenAPI spec via overlay content/spec-first/overlays.md#add-examples

Add API-response-based examples to spec content/spec-first/overlays.md#add-examples

Test SDK against live API content/sdk-testing/integration-testing.md

Run contract tests for generated SDK content/sdk-testing/contract-testing.md

Directory Structure

content/ ├── INDEX.md # This index (SKILL.md) ├── plans/ # Decision trees for workflows │ ├── sdk-generation.md # Full SDK generation workflow │ └── tf-provider-generation.md ├── code-first/ # Extract OpenAPI from code │ ├── fastapi.md │ ├── flask.md │ ├── django.md │ ├── spring-boot.md │ ├── nestjs.md │ ├── hono.md │ ├── rails.md │ └── laravel.md ├── spec-first/ # OpenAPI validation and fixes │ ├── validation.md │ ├── overlays.md # OpenAPI overlays and recipes │ ├── security-schemes.md │ ├── pagination.md │ └── schemas.md ├── sdk-languages/ # Language-specific SDK guides │ ├── python.md │ ├── typescript.md # TS: code regions, extra modules, Zod │ ├── go.md # Go: hooks, interfaces, mocks, K8s │ ├── java.md │ ├── csharp.md │ ├── ruby.md # Ruby: Sorbet typing, RubyGems publishing │ └── php.md ├── sdk-customization/ # Cross-language SDK customization │ ├── hooks.md # SDK hooks (UA, telemetry, custom security) │ ├── runtime-configuration.md # Retries, timeouts, pagination, servers │ ├── authentication-config.md # Global/per-op security, env vars │ ├── error-handling.md # Custom error classes and schemas │ ├── custom-code.md # Persist changes across regenerations │ ├── multi-target-sdks.md # Multiple variants from one repo │ ├── multi-repo-workflows.md # Cross-repo SDK orchestration (CI/CD) │ ├── mcp-server.md # MCP server for AI assistant integration │ └── readme-customization.md # SDK README branding ├── sdk-testing/ # SDK testing patterns │ ├── integration-testing.md # Integration test infrastructure │ ├── arazzo-testing.md # Arazzo API testing format │ └── contract-testing.md # AI-powered contract testing ├── terraform/ # Terraform provider specifics │ ├── crud-mapping.md │ ├── customization.md │ ├── testing-guide.md │ └── publishing.md └── CLI_REFERENCE.md # Canonical CLI command documentation

Decision Tree: Where to Start

START │ ├─ Do you have an OpenAPI/Swagger spec? │ │ │ ├─ YES ──► Is the spec valid? │ │ │ │ │ ├─ YES ──► What do you want to generate? │ │ │ │ │ │ │ ├─ SDK ──► plans/sdk-generation.md │ │ │ └─ Terraform Provider ──► plans/tf-provider-generation.md │ │ │ │ │ └─ NO/UNSURE ──► spec-first/validation.md │ │ │ └─ NO ──► Do you have API code? │ │ │ ├─ YES ──► What framework? │ │ ├─ FastAPI ──► code-first/fastapi.md │ │ ├─ Flask ──► code-first/flask.md │ │ ├─ Django ──► code-first/django.md │ │ ├─ Spring Boot ──► code-first/spring-boot.md │ │ ├─ NestJS ──► code-first/nestjs.md │ │ ├─ Hono ──► code-first/hono.md │ │ ├─ Rails ──► code-first/rails.md │ │ └─ Laravel ──► code-first/laravel.md │ │ │ └─ NO ──► Cannot proceed without spec or code

Troubleshooting Tree

PROBLEM │ ├─ Getting ResponseValidationError at runtime? │ │ │ └─ SDK types don't match server responses │ ├─ Run contract tests to identify all mismatches │ │ → sdk-testing/contract-testing.md │ └─ Fix spec or create overlay to correct types │ → spec-first/validation.md#dynamic-validation-contract-testing │ ├─ SDK doesn't match live API behavior? │ │ │ ├─ Spec may have drifted from API │ │ → Run contract tests to detect drift │ │ sdk-testing/contract-testing.md │ │ │ └─ Third-party spec may be inaccurate │ → Validate with contract testing before trusting │ sdk-testing/contract-testing.md │ ├─ Type mismatch errors in generated SDK? │ │ │ ├─ At compile time ──► Check spec schema definitions │ │ spec-first/validation.md │ │ │ └─ At runtime ──► Server returns unexpected types │ → Contract testing required │ sdk-testing/contract-testing.md │ └─ Enum value not recognized? │ └─ API returned value not in spec enum ├─ Add missing value to spec/overlay │ → spec-first/overlays.md └─ Or use open enums for anti-fragility → spec-first/overlays.md#overlay-recipes

Working with Large OpenAPI Documents

OpenAPI specs can be thousands of lines. Do not load the full spec into context. Use yq (YAML) or jq (JSON) to extract only the sections you need.

List all paths

yq '.paths | keys' spec.yaml

Inspect a specific endpoint

yq '.paths["/users/{id}"]' spec.yaml

List all schema names

yq '.components.schemas | keys' spec.yaml

Inspect a specific schema

yq '.components.schemas.User' spec.yaml

Check server URLs

yq '.servers' spec.yaml

List all operationIds

yq '[.paths[][].operationId // empty] | unique' spec.yaml

For JSON specs, use jq

jq '.paths | keys' spec.json jq '.components.schemas.User' spec.json

Note: If yq /jq aren't available, use targeted grep searches instead of copying the full spec into context:

grep -n 'operationId:' spec.yaml grep -n 'x-speakeasy-entity' spec.yaml

Common Workflows

Workflow A: First-Time SDK Generation

• Read content/plans/sdk-generation.md

• Run speakeasy quickstart --skip-interactive --output console -s spec.yaml -t python -o ./sdk

• SDK generated in output directory

Workflow B: Existing Codebase → SDK

• Identify framework in content/code-first/

• Extract OpenAPI spec

• Validate with speakeasy lint openapi --non-interactive -s spec.yaml

• Fix issues using content/spec-first/ guides

• Generate SDK via content/plans/sdk-generation.md

Workflow C: SDK Customization

• Ensure gen.yaml exists (from quickstart)

• Read content/sdk-customization/ guides

• Modify gen.yaml

• Regenerate with speakeasy run -y --output console

Workflow D: Multi-Target SDK (Azure, GCP, etc.)

• Read content/sdk-customization/multi-target-sdks.md

• Configure multiple sources in workflow.yaml

• Set up target outputs to packages/ subdirectories

• Create CI workflows per target

Workflow E: SDK Extensions (Hooks, Custom Methods)

• For persistent changes anywhere → content/sdk-customization/custom-code.md

• For cross-cutting concerns → content/sdk-customization/hooks.md

• For predefined extension points → content/sdk-languages/typescript.md#custom-code-regions

• For complex logic → content/sdk-languages/typescript.md#extra-modules-pattern

Workflow F: Upgrade and Regenerate

• Check current speakeasyVersion in .speakeasy/workflow.yaml

• Update speakeasyVersion to latest or a specific version → content/plans/sdk-generation.md#version-management

• Regenerate with speakeasy run → content/plans/sdk-generation.md

• Test the regenerated SDK → content/sdk-testing/integration-testing.md or content/sdk-testing/contract-testing.md

• Commit changes

Essential CLI Commands

Command Purpose

speakeasy quickstart --skip-interactive --output console -s spec.yaml -t python -o ./sdk

Non-interactive SDK setup

speakeasy run -y --output console

Regenerate SDK from gen.yaml

speakeasy lint openapi --non-interactive -s spec.yaml

Validate OpenAPI spec

speakeasy auth login

Authenticate with Speakeasy

Getting Help

• Authentication issues: Run speakeasy auth login

• Validation errors: See content/spec-first/validation.md

• Unsupported feature: Check language guide in content/sdk-languages/

• CLI errors: See content/CLI_REFERENCE.md or run speakeasy --help

Providing Feedback

If you encounter missing documentation, unclear instructions, or incorrect examples in this agent context, submit feedback directly:

General feedback

speakeasy agent feedback -m "Description of the issue or suggestion"

Feedback about a specific document

speakeasy agent feedback -m "Description of the issue" --context-path "path/to/document.md"

Feedback helps improve these documents for all agents. Submit feedback when:

• A guide is missing steps needed to complete a task

• An example does not work as documented

• A CLI command behaves differently than described

• You cannot find documentation for a supported feature

Related Skills

• start-new-sdk-project

• Quick interactive setup with speakeasy quickstart

• regenerate-sdk

• Re-run generation after config changes

• validate-openapi-spec

• Lint and validate OpenAPI specs

• diagnose-generation-failure

• Troubleshoot failed generation runs

• create-openapi-overlay

• Create overlays for spec customization

• fix-validation-errors-with-overlays

• Fix lint errors with overlays