openapi-gen
Generate and validate Python clients from OpenAPI specs. Use for generation, validation, or troubleshooting.
When & Why to Use This Skill
This Claude skill automates the generation and validation of type-safe Python clients from OpenAPI specifications. It streamlines the development workflow by reducing manual boilerplate, ensuring API compatibility, and providing built-in troubleshooting tools for seamless REST API integration and SDK maintenance.
Use Cases
- Rapid SDK Bootstrapping: Quickly generate robust Python client libraries for any REST API defined by an OpenAPI/Swagger specification, saving hours of manual coding.
- API Specification Validation: Use the generation and type-checking workflow to identify inconsistencies, missing fields, or structural errors in OpenAPI schemas.
- Multi-Client Architecture Management: Efficiently manage multiple API integrations within a single project by utilizing shared core modules to reduce code duplication.
- Automated Integration Testing: Incorporate client generation into CI/CD pipelines to ensure that Python consumers stay in sync with evolving backend API definitions.
| name | openapi-gen |
|---|---|
| description | Generate and validate Python clients from OpenAPI specs. Use for generation, validation, or troubleshooting. |
| allowed-tools | Bash, Read, Glob, Grep |
OpenAPI Client Generation
Workflow
- Activate:
source .venv/bin/activate - Generate:
pyopenapi-gen <spec> --project-root <path> --output-package <pkg> --force --verbose - Validate:
- Check warnings in output
- Test:
python -c "from <pkg> import *" - Type check:
mypy <path>/<pkg> --ignore-missing-imports
Options
| Option | Purpose |
|---|---|
--force |
Overwrite existing files |
--no-postprocess |
Skip Black/mypy (faster iteration) |
--core-package |
Shared core for multi-client setups |
--verbose |
Show detailed progress |
Common Issues
| Symptom | Fix |
|---|---|
| Import error | Check --project-root and --output-package alignment |
| Missing module | Check --verbose for cycle warnings |
| Type error | Review OpenAPI spec |
| Empty dataclass | Ensure schema has type field |
Multi-Client Setup
For shared core module:
# First client with core
pyopenapi-gen api1.yaml --project-root . --output-package clients.api1 --core-package clients.core
# Additional clients sharing core
pyopenapi-gen api2.yaml --project-root . --output-package clients.api2 --core-package clients.core