Package: openapi-python-client
openapi-python-clientGenerate 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 featuresWhy This?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.InstallationI recommend you install withpipxso you don't conflict with any other packages you might have:pipx install openapi-python-client --include-deps.Note the--include-depsoption makesruffavailable in your path so thatopenapi-python-clientcan use it to clean up the generated code.If you usepipx runthen the post-generation hooks will not be available unless you install them manually.You can also install with normal pip:pip install openapi-python-clientThen, if you want tab completion:openapi-python-client --install-completionUsageCreate a new clientopenapi-python-client generate --url https://my.api.com/openapi.jsonThis 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 anopenapi.jsonfile available on disk, in any CLI invocation you can build off that instead by replacing--urlwith a--path:openapi-python-client generate --path location/on/disk/openapi.jsonUpdate an existing clientopenapi-python-client update --url https://my.api.com/openapi.jsonUsing custom templatesThis feature leverages Jinja2'sChoiceLoaderandFileSystemLoader. This means you donotneed to customize every template. Simply copy the template(s) you want to customize fromthe default template directoryto your own custom template directory (file namesmustmatch exactly) and pass the template directory through thecustom-template-pathflag to thegenerateandupdatecommands. For instance,openapi-python-client update \
  --url https://my.api.com/openapi.json \
  --custom-template-path=relative/path/to/mytemplatesBe forewarned, this is a beta-level feature in the sense that the API exposed in the templates is undocumented and unstable.What You GetApyproject.tomlfile, optionally withPoetrymetadata (default),PDM(with--meta=pdm), or onlyRuffconfig.AREADME.mdyou'll most definitely need to update with your project's detailsA Python module named just like the auto-generated project name (e.g. "my_api_client") which contains:Aclientmodule which will have both aClientclass and anAuthenticatedClientclass. You'll need these
for calling the functions in theapimodule.Anapimodule which will contain one module for each tag in your OpenAPI spec, as well as adefaultmodule
for endpoints without a tag. Each of these modules in turn contains one function for calling each endpoint.Amodelsmodule which has all the classes defined by the various schemas in your OpenAPI specAsetup.pyfileifyou use--meta=setup(default is--meta=poetry)For a full example you can look at theend_to_end_testsdirectory which hasbaseline_openapi_3.0.jsonandbaseline_openapi_3.1.yamlfiles.
The "golden-record" in that same directory is the generated client from either of those OpenAPI documents.ConfigurationYou can pass a YAML (or JSON) file to openapi-python-client with the--configoption in order to change some behavior.
The following parameters are supported:class_overridesUsed 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 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_nameThe easiest way to find what needs to be overridden is probably to generate your client and go look at everything in themodelsfolder.project_name_override and package_name_overrideUsed 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-'s with_'s).Example:project_name_override:my-special-project-namepackage_name_override:my_extra_special_package_namefield_prefixWhen generating properties, thenameattribute of the OpenAPI schema will be used. When thenameis 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_package_version_overrideSpecify 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.3post_hooksIn the config file, there's an easy way to tellopenapi-python-clientto 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:-"ruffcheck.--fix"-"ruffformat."use_path_prefixes_for_title_model_namesBy default,openapi-python-clientgenerates 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 yourtitleproperties already to ensure no duplicate class names, you can turn off this prefixing feature by settinguse_path_prefixes_for_title_model_namestofalsein your config file. This will use thetitleproperty of any object that has it setwithoutprefixing.If this option results in conflicts, you will need to manually override class names instead via theclass_overridesoption.http_timeoutBy 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.