Generating API SDKs
Overview
Generate type-safe client SDKs in multiple languages (TypeScript, Python, Go, Java) from OpenAPI 3.0+ specifications. Produce idiomatic client libraries with authentication handling, automatic retries, pagination helpers, and comprehensive type definitions that mirror the API contract.
Prerequisites
- OpenAPI 3.0+ specification file (YAML or JSON) with complete schema definitions
- Target language toolchain installed (Node.js/TypeScript, Python 3.10+, Go 1.21+, or Java 17+)
- OpenAPI Generator CLI or equivalent code generation tool
- Package registry credentials for publishing (npm, PyPI, Maven Central, pkg.go.dev)
- CI pipeline for automated SDK builds on spec changes
Instructions
- Read and validate the OpenAPI specification using Read, checking for complete schema definitions, proper
$refusage, and response type coverage across all endpoints. - Extract all operation IDs, request/response models, and authentication schemes from the specification to build the SDK method inventory.
- Generate typed model classes for every schema component, including nested objects, enums, and discriminated unions with proper nullability annotations.
- Create a client class with methods for each API operation, mapping operation IDs to idiomatic method names (e.g.,
listUsers,get_user,CreateUser). - Implement authentication handling with support for Bearer tokens, API keys (header and query), and OAuth2 client credentials flow, configurable at client instantiation.
- Add automatic retry logic with exponential backoff for 429 and 5xx responses, with configurable max retries and backoff multiplier.
- Build pagination helpers that abstract cursor-based and offset pagination into iterator/generator patterns native to each target language.
- Generate comprehensive JSDoc/docstring/Javadoc comments from OpenAPI
descriptionandsummaryfields for full IDE IntelliSense support. - Create a test suite that validates SDK methods against a mock server running the OpenAPI spec, covering authentication, error handling, and pagination.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/sdk/typescript/src/client.ts- Main SDK client class with typed methods${CLAUDE_SKILL_DIR}/sdk/typescript/src/models/- TypeScript interfaces and type definitions${CLAUDE_SKILL_DIR}/sdk/python/client.py- Python SDK with dataclass models and async support${CLAUDE_SKILL_DIR}/sdk/go/client.go- Go SDK with struct types and context-based methods${CLAUDE_SKILL_DIR}/sdk/*/README.md- Per-language installation and usage documentation${CLAUDE_SKILL_DIR}/sdk/*/tests/- SDK test suites per language
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Schema generation failure | OpenAPI spec contains $ref cycles or missing component definitions | Run spec linting with spectral first; resolve circular references with allOf composition |
| Type mismatch | API response does not match generated model types at runtime | Add runtime response validation option; log schema drift warnings for API provider notification |
| Auth configuration error | SDK instantiated without required credentials for protected endpoints | Throw descriptive error at client construction time listing required auth parameters |
| Pagination exhaustion | Iterator consumes all pages without termination condition | Enforce maximum page count safety limit; detect empty result sets as termination signal |
| Rate limit handling | SDK retry logic conflicts with application-level retry logic | Expose retryConfig option to disable built-in retries; emit retry events for observability |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
TypeScript SDK for payment API: Generate a fully typed PaymentsClient with methods like createCharge(amount, currency) returning Promise<Charge>, automatic Bearer token injection, and paginated listTransactions() returning an async iterator.
Python SDK with async support: Produce both sync (PaymentsClient) and async (AsyncPaymentsClient) clients using httpx, with Pydantic models for request/response validation and __aiter__ pagination support.
Multi-language CI pipeline: On OpenAPI spec change, automatically regenerate SDKs in all target languages, run tests against a mock server, bump semantic versions, and publish to respective package registries.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
- OpenAPI Generator: https://openapi-generator.tech/
- Speakeasy SDK generation: https://speakeasy.com/
- Microsoft Kiota for API client generation
- OpenAPI Specification 3.1: https://spec.openapis.org/oas/v3.1.0