How codegen-sh/codegen-api-client works
Project Type and Purpose
• This is a *client SDK generator* library.
• Purpose: generate a Python client (codegen_api_client/openapi_client) from an OpenAPI spec so that application developers can call a REST API in a typed, ergonomic way.
File Structure
Top‐level artifacts:
• gen/openapi.yaml + gen/config.json – the OpenAPI definition and generation settings
• .openapi-generator/… – metadata controlling generator behavior
• codegen_api_client/ & openapi_client/ – two sibling output packages (namespaces for generated code)
– api/ – HTTP method wrappers (AgentsApi, OrganizationsApi, UsersApi)
– models/ – data model classes for request/response bodies
– api_client.py, configuration.py – core HTTP client, host/settings
– exceptions.py, api_response.py, rest.py – error handling, low-level transport
• docs/ – Markdown docs for each model and endpoint
• test/ – pytest suite verifying model serialization and API calls
• pyproject.toml, tox.ini – build and test configuration
• CI/CD pipelines (.github/workflows, .travis.yml, .gitlab-ci.yml) – automate build, test, release
• git_push.sh – helper script to push releases
README for Additional Insights
• The README confirms:
– Package auto-generated by OpenAPI Generator
– Usage pattern: configure host → with ApiClient → instantiate API class → call methods
– No authorization required
– API versioning and generator version metadata
Main Components and Interactions
A. OpenAPI Generator Pipeline (build-time)
1. Input: gen/openapi.yaml + gen/config.json
2. OpenAPI Generator (CLI or Maven plugin) reads .openapi-generator settings
3. Output: code files under codegen_api_client/ and openapi_client/
4. Packaging: pyproject.toml defines metadata → build wheel / sdist
5. CI/CD:
• Run pytest against test/
• If tests pass, publish to PyPI (uv pip push)
B. Generated Client Library (run-time)
1. Consumer code imports codegen_api_client
2. Configuration(host, timeouts, headers)
3. ApiClient manages HTTP session (RestClient)
4. AgentsApi, OrganizationsApi, UsersApi wrap service endpoints
5. Models serialize/deserialize JSON payloads
6. ApiResponse and ApiException handle success / error flows
Architectural Patterns and Design Principles
• Layered Structure:
– Transport Layer (Rest, HTTPClient)
– API Layer (ApiClient + per-resource Api classes)
– Model Layer (Pydantic-style classes or plain dataclasses)
• Separation of Concerns:
– Codegen-specific config and templates isolated under .openapi-generator
– Generated code kept in its own namespace
• Extensibility:
– New endpoints appear as new methods in Api classes when spec changes
– New models generated automatically
• Test-Driven Validation:
– Each model and API method has corresponding pytest
Final Checklist
– [ ] Call out key configuration files (pyproject.toml, gen/config.json)
– [ ] Show CI/CD workflows triggering tests and release