Generate modern Python clients from OpenAPI
Generate modern Python clients from OpenAPI 3.x 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
The Python clients generated by openapi-generator support Python 2 and therefore come with a lot of baggage. This tool aims to generate clients which:
- Use all the latest and greatest Python features like type annotations and dataclasses
- Don't carry around a bunch of compatibility code for older version of Python (e.g. the
- Have better documentation and more obvious usage instructions
Additionally, because this generator is written in Python, it should be more accessible to contribution by the people using it (Python developers).
I recommend you install with pipx so you don't conflict with any other packages
you might have:
pipx install openapi-python-client.
Better yet, use
pipx run openapi-python-client <normal params / options> to always use the latest version of the generator.
You can install with normal pip if you want to though:
pip install openapi-python-client
Then, if you want tab completion:
Create a new client
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". If a folder already exists by that name, you'll get an error.
If you have an
openapi.json file available on disk, in any CLI invocation you can build off that instead by replacing
--url with a
openapi-python-client generate --path location/on/disk/openapi.json
Update an existing client
openapi-python-client update --url https://my.api.com/openapi.json
For more usage details run
openapi-python-client --helpor read usage
Using custom templates
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
update commands. For instance,
openapi-python-client update \ --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.
What You Get
pyproject.tomlfile with some basic metadata intended to be used with Poetry.
README.mdyou'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:
clientmodule which will have both a
Clientclass and an
AuthenticatedClientclass. You'll need these for calling the functions in the
apimodule which will contain one module for each tag in your OpenAPI spec, as well as a
defaultmodule for endpoints without a tag. Each of these modules in turn contains one function for calling each endpoint.
modelsmodule which has all the classes defined by the various schemas in your OpenAPI spec
For a full example you can look at the
end_to_end_tests directory which has an
"golden-record" in that same directory is the generated client from that OpenAPI document.
OpenAPI features supported
- All HTTP Methods
- JSON and form bodies, path and query parameters
- File uploads with multipart/form-data bodies
- float, string, int, date, datetime, string enums, and custom schemas or lists containing any of those
- html/text or application/json responses containing any of the previous types
- Bearer token security
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:
Used to change the name of generated model classes. This param should be a mapping of existing class name (usually a key in the "schemas" section of your OpenAPI document) to class_name and module_name. As an example, if the name of the a model in OpenAPI (and therefore the generated class name) was something like "_PrivateInternalLongName" and you want the generated client's model to be called "ShortName" in a module called "short_name" you could do this:
class_overrides: _PrivateInternalLongName: class_name: ShortName module_name: short_name
The easiest way to find what needs to be overridden is probably to generate your client and go look at everything in the models folder.
project_name_override and package_name_override
Used to change the name of generated client library project/package. If the project name is changed but an override for the package name
isn't provided, the package name will be converted from the project name using the standard convention (replacing
project_name_override: my-special-project-name package_name_override: my_extra_special_package_name
When generating properties, the
name attribute of the OpenAPI schema will be used. When the
name is not a valid
Python identifier (e.g. begins with a number) this string will be prepended. Defaults to "field_".
Specify the package version of the generated client. If unset, the client will use the version of the OpenAPI spec.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size openapi_python_client-0.10.1-py3-none-any.whl (94.0 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size openapi-python-client-0.10.1.tar.gz (63.5 kB)||File type Source||Python version None||Upload date||Hashes View|
Hashes for openapi_python_client-0.10.1-py3-none-any.whl
Hashes for openapi-python-client-0.10.1.tar.gz