Generate modern Python clients from OpenAPI
This project is still in early 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
six
package) - 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: 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". If a folder already exists by that name, you'll get an error.
openapi-python-client update --url https://my.api.com/openapi.json
For more usage details run
openapi-python-client --help
or read usage
- A
pyproject.toml
file with some basic metadata intended to be used with Poetry. - 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
For a full example you can look at the test_end_to_end
directory which has a declared FastAPI
server and the resulting openapi.json file in the "fastapi" directory. "golden-master" is the generated client from that
OpenAPI document.
- 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:
Example:
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.