Generate modern Python clients from OpenAPI 3.0 and 3.1 documents.
This generator does not support OpenAPI 2.x FKA Swagger. If you need to use an older document, try upgrading it to version 3 first with one of many available converters.
This project is still in development and does not support all OpenAPI features
This tool focuses on creating the best developer experience for Python developers by:
- Using all the latest and greatest Python features like type annotations and dataclasses.
- Having documentation and usage instructions specific to this one generator.
- Being written in Python with Jinja2 templates, making it easier to improve and extend for Python developers. It's also much easier to install and use if you already have Python.
I recommend you install with pipx so you don't conflict with any other packages you might have: pipx install openapi-python-client --include-deps
.
Note the
--include-deps
option makesruff
available in your path so thatopenapi-python-client
can use it to clean up the generated code.
If you use pipx run
then the post-generation hooks will not be available unless you install them manually.
You can also install with normal pip: pip install openapi-python-client
Then, if you want tab completion: openapi-python-client --install-completion
openapi-python-client generate --url https://my.api.com/openapi.json
This will generate a new client library named based on the title in your OpenAPI spec. For example, if the title
of your API is "My API", the expected output will be "my-api-client". You can change that directory name with the config file (documented below) or with --output-path
.
If the directory to generate already exists, you'll get an error unless you use --overwrite
.
You can use an OpenAPI file instead of a URL like openapi-python-client generate --path location/on/disk/openapi.json
.
This feature leverages Jinja2's ChoiceLoader and FileSystemLoader. This means you do not need to customize every template. Simply copy the template(s) you want to customize from the default template directory to your own custom template directory (file names must match exactly) and pass the template directory through the custom-template-path
flag to the generate
command:
openapi-python-client generate \
--url https://my.api.com/openapi.json \
--custom-template-path=relative/path/to/mytemplates
Be forewarned, this is a beta-level feature in the sense that the API exposed in the templates is undocumented and unstable.
- A
pyproject.toml
file, optionally with Poetry metadata (default), PDM (with--meta=pdm
), or only Ruff config. - A
README.md
you'll most definitely need to update with your project's details - A Python module named just like the auto-generated project name (e.g. "my_api_client") which contains:
- A
client
module which will have both aClient
class and anAuthenticatedClient
class. You'll need these for calling the functions in theapi
module. - An
api
module which will contain one module for each tag in your OpenAPI spec, as well as adefault
module for endpoints without a tag. Each of these modules in turn contains one function for calling each endpoint. - A
models
module which has all the classes defined by the various schemas in your OpenAPI spec
- A
- A
setup.py
file if you use--meta=setup
(default is--meta=poetry
)
For a full example you can look at the end_to_end_tests
directory which has baseline_openapi_3.0.json
and baseline_openapi_3.1.yaml
files.
The "golden-record" in that same directory is the generated client from either of those OpenAPI documents.
You can pass a YAML (or JSON) file to openapi-python-client with the --config
option in order to change some behavior.
The following parameters are supported: