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
$ref usage, 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
description and summary fields 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 ${CLAUDESKILLDIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDESKILLDIR}/sdk/typescript/src/client.ts - Main SDK client class with typed methods${CLAUDESKILLDIR}/sdk/typescript/src/models/ - TypeScript interfaces and type definitions${CLAUDESKILLDIR}/sdk/python/client.py - Python SDK with dataclass models and async support${CLAUDESKILLDIR}/sdk/go/client.go - Go SDK with struct types and context-based methods${CLAUDESKILLDIR}/sdk/*/README.md - Per-langu