Repository files navigation

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 toversion 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:

1. Using all the latest and greatest Python features like type annotations and dataclasses.
2. Having documentation and usage instructions specific to this one generator.
3. 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 withpipx 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 usepipx 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 titleof 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 likeopenapi-python-client generate --path location/on/disk/openapi.json.

This feature leverages Jinja2'sChoiceLoader andFileSystemLoader. This means you donot need to customize every template. Simply copy the template(s) you want to customize fromthe default template directory to your own custom template directory (file namesmust match exactly) and pass the template directory through thecustom-template-path flag to thegenerate 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.

1. Apyproject.toml file, optionally withPoetry metadata (default),PDM (with--meta=pdm), or onlyRuff config.
2. AREADME.md you'll most definitely need to update with your project's details
3. A Python module named just like the auto-generated project name (e.g. "my_api_client") which contains:
   1. Aclient module which will have both aClient class and anAuthenticatedClient class. You'll need thesefor calling the functions in theapi module.
   2. Anapi module which will contain one module for each tag in your OpenAPI spec, as well as adefault modulefor endpoints without a tag. Each of these modules in turn contains one function for calling each endpoint.
   3. Amodels module which has all the classes defined by the various schemas in your OpenAPI spec
4. Asetup.py fileif you use--meta=setup (default is--meta=poetry)

For a full example you can look at theend_to_end_tests directory which hasbaseline_openapi_3.0.json andbaseline_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:

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 thename of 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:ShortNamemodule_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 themodels folder.

By default, whenopenapi-python-client generates a model class, it includes a list of attributes and theirdescriptions in the docstring for the class. If you set this option totrue, then the attribute descriptionswill be put in docstrings for the attributes themselves, and will not be in the class docstring.

docstrings_on_attributes:true

By default,openapi-python-client generates classes inheriting forEnum for enums. It can instead useLiteralvalues for enums by setting this totrue:

literal_enums:true

This is especially useful if enum values, when transformed to their Python names, end up conflicting due to case sensitivity or special symbols.

openapi-python-client generates module names within theapi module based on the OpenAPItags of each endpoint.By default, only thefirst tag is generated. If you want to generateduplicate endpoint functions usingevery taglisted, you can enable this option:

generate_all_tags:true

Used to change the name of generated client library project/package. If the project name is changed but an override for the package nameisn't provided, the package name will be converted from the project name using the standard convention (replacing-'s with_'s).

Example:

project_name_override:my-special-project-namepackage_name_override:my_extra_special_package_name

When generating properties, thename attribute of the OpenAPI schema will be used. When thename is not a valid Python identifier (e.g. begins with a number) this string will be prepended. Defaults to "field_". It will also be used to prefix fields in schema starting with "_" in order to avoid ambiguous semantics.

Example:

field_prefix:attr_

Specify the package version of the generated client. If unset, the client will use the version of the OpenAPI spec.

Example:

package_version_override:1.2.3

In the config file, there's an easy way to tellopenapi-python-client to run additional commands after generation. Here's an example showing the default commands (usingRuff) that will run if you don't override them in config:

post_hooks:   -"ruff check . --fix"   -"ruff format ."

By default,openapi-python-client generates class names which include the full path to the schema, including any parent-types. This can result in very long class names likeMyRouteSomeClassAnotherClassResponse—which is very unique and unlikely to cause conflicts with future API additions, but also super verbose.

If you are carefully curating yourtitle properties already to ensure no duplicate class names, you can turn off this prefixing feature by settinguse_path_prefixes_for_title_model_names tofalse in your config file. This will use thetitle property of any object that has it setwithout prefixing.

If this option results in conflicts, you will need to manually override class names instead via theclass_overrides option.

By default, the timeout for retrieving the schema file via HTTP is 5 seconds. In case there is an error when retrieving the schema, you might try and increase this setting to a higher value.

Normally,openapi-python-client will skip any bodies or responses that it doesn't recognize the content type for.This config tells the generator to treat a given content type like another.

content_type_overrides:application/zip:application/octet-stream

This extension has been adopted by similar projects such asOpenAPI Tools.It is intended to provide user-friendly names for integer Enum members that get generated.It is critical that the length of the array matches that of the enum values.

"Colors": {   "type": "integer",   "format": "int32",   "enum": [       0,       1,       2   ],   "x-enum-varnames": [      "Red",      "Green",      "Blue"   ]}

Results in:

class Color(IntEnum):    RED = 0    GREEN = 1    BLUE = 2