UitbreidenOS When to activate
- Generating client SDKs from OpenAPI specs
- Creating typed API clients for TypeScript/JavaScript
- Building Python client libraries with type hints
- Setting up auto-generated SDKs in CI/CD pipelines
- Maintaining SDK parity with API changes
When NOT to use
- For manual API wrapper development
- For GraphQL client generation
- For internal RPC client stubs
Instructions
- Validate OpenAPI spec. Ensure spec passes spectral linting before generation — garbage in, garbage out.
- Select generator. OpenAPI Generator, Speakeasy, or Fern depending on quality requirements.
- Configure generator. Set package name, version, output directory, and language-specific options.
- Generate SDK. Run generator; review output for completeness and type safety.
- Add customizations. Custom HTTP client configuration, retry logic, timeout overrides, and middleware hooks.
- Write usage examples. 3-5 examples covering common workflows: CRUD operations, pagination, error handling.
- Publish SDK. Configure npm/PyPI/Go module publishing in CI pipeline triggered by spec changes.
Example
// Generated TypeScript SDK usage
import { UsersApi } from '@company/api-sdk';
const api = new UsersApi({ apiKey: process.env.API_KEY });
// List users with pagination
const users = await api.listUsers({ page: 1, limit: 20 });
console.log(users.data); // User[]
console.log(users.meta.total); // number
// Error handling
try {
await api.createUser({ email: 'invalid' });
} catch (err) {
if (err instanceof ValidationError) {
console.log(err.details); // FieldError[]
}
}