FastAPI-based API Client Generator
Generate a mypy- and IDE-friendly API client from an OpenAPI spec.
- Sync and async interfaces are both available
- Comes with support for the OAuth2.0 password flow
- Easily extended, with built-in support for request middleware
- Designed for integration with FastAPI, but should work with most OpenAPI specs
- Makes use of https://github.com/OpenAPITools/openapi-generator
Look inside example/client to see an example of the generated output!
Warning: This is still in the proof-of-concept phase, and should not yet be considered to have a stable interface.
- Some OpenAPI features (like discriminator fields) are not yet supported.
- While the goal is to support any OpenAPI spec, it is most likely to work well with specs generated by FastAPI.
If you try this out, please help me by reporting any issues you notice!
Client library usage
from client.api_client import ApiClient, AsyncApis, SyncApis
from client.models import Pet
client = ApiClient(host="http://localhost")
sync_apis = SyncApis(client)
async_apis = AsyncApis(client)
pet_1 = sync_apis.pet_api.get_pet_by_id(pet_id=1)
assert isinstance(pet_1, Pet)
async def get_pet_2() -> Pet:
pet_2 = await async_apis.pet_api.get_pet_by_id(pet_id=2)
assert isinstance(pet_2, Pet)
return pet_2
The example generated client library is contained in example/client.
Generated clients will have the following dependencies:
pydanticfor modelshttpxfor networkingfastapiforjsonable_encoderand OAuth models (I hope to eventually remove this as a dependency)typing_extensionsfor Enums viaLiteral(I eventually hope to replace this with standard enums)
More examples of usage (including auth) are contained in example/usage_example.py.
Generating the client library
Using the generator looks like
./scripts/generate.sh -i <openapi_json> -p <package_name> -o <output_path>
[-n <import_name>] [--include-auth]
[--] [*openapi-generator-args]
and will produce a client library at <output_path>/<package_name>.
The OpenAPI json input can be either a URL or a local file path.
For example, running
./scripts/generate.sh \
-i https://petstore.swagger.io/v2/swagger.json \
-p client \
-o generated \
-n example.client \
--include-auth
produces the example client (along with the OAuth2.0 password flow client), places it in generated/client, and makes any generated client-referencing imports start with example.client.
(Note: to prevent accidental overwrites, you would need to manually remove generated/client if it already exists.)
With FastAPI
-
To generate a client for a default FastAPI app running on localhost (NOT inside a docker container):
./scripts/generate.sh -i http://localhost/openapi.json -p my_client -o generated -
Since the generator runs inside docker, if your server is also running in a docker container on the same machine, you may need to provide a special hostname. Passing the
--map-localhostargument will make the script attempt to perform this automatically:./scripts/generate.sh --map-localhost -i http://localhost/openapi.json -p my_client -o generated # Transforms the input to http://host.docker.internal/openapi.json
Generation details
- The only local dependencies for generation are
dockerand standard command line tools. openapi-generatoris used to generate the code from the openapi spec- The custom templates are located in
openapi-python-templates
- The custom templates are located in
autoflake,isort, andblackare used to format the code after generation
Contributing
There are a variety of make rules for setup/testing; here are some highlights:
make develop: Sets up the local development environment.make regenerate: Regenerates the example client from the example's openapi.json and the templates.- Note: This will overwrite changes! Make sure you commit (or edit the templates) before running this.
make: Checks that isort, black, flake8, mypy, and pytest all passmake testcov: Generates a coverage report for the tests.
Pull requests are welcome and appreciated!
1k Jan 2, 2023
1 Oct 8, 2022
9 Nov 10, 2022
2 Jan 17, 2022
1 Jan 1, 2022
5 Dec 23, 2022
14 Dec 5, 2022
27 Oct 16, 2022
29 Nov 20, 2022
318 Dec 31, 2022
632 Jan 5, 2023
10.8k Jan 8, 2023
950 Jan 8, 2023
465 Jan 7, 2023
543 Jan 5, 2023
1.3k Jan 4, 2023
239 Dec 28, 2022
225 Jan 5, 2023
1.4k Jan 2, 2023