Autogenerating clients with FastAPI and Github Actions

If youve ever hand-written a javascript/typescript client for an API, you probably know the pain of writing a subtle bug. Maybe you missed a query parameter or did some copy/pasting that you forgot to modify. Or maybe the API just changed later on and the client was never updated. While they may be simple mistakes, they are a pain to debug and coordination problems like these will only get worse as your team grows.

Coordination via OpenAPI +FastAPI

One solution to this challenge is OpenAPIa spec that allows you to write JSON or YML, which describes your API. You can then autogenerate clients and servers in different languages and guarantee that the client and server are in sync.

However, a problem that Ive always had with this approach is that I personally dont like editing the OpenAPI spec for every change I want to make. While there are tools that make the process easier, as a backend developer, I prefer to update my routes directly on the backend.

This is where FastAPI comes in. FastAPI is a python web framework with a lot of thoughtful features. One of my favorite features is that it will generate an OpenAPI spec from the code you write. For example, lets use this app:

from typing import Unionfrom fastapi import FastAPIapp = FastAPI()@app.get("/hello")async def hello(name: Union[str, None] = None):    if name is None:        return {"message": "Hello World"}    else:        return {"message": f"Hello {name}"}

This is a simple app that has one route, an optional query parameter, and a JSON response.

Next, run the server:

$ uvicorn main:app

Then navigate to http://localhost:8000/openapi.json, where youll see the OpenAPI spec that matches the API.

API First Design

This changes the workflow from:

Update OpenAPI schema Generate server routes Generate clients

to:

Update your server Generate the OpenAPI schema Generate the clients

While there are merits to both, the FastAPI version feels way more natural to me as it gets my backend into a good state and then has everything else derive from that.

Automatically updating the clients with Github Actions

If theres only one client of your API, its not so bad to re-generate it every time you need make a change. But as the number of clients increases or your team size increases, youll want to automate this process in order to avoid drowning in manual updates.

Adding in Github Actions will enable you to generate new clients on every commit. Lets first look at the action and then break it down:

name: Generate clientson: pushjobs:  generate-clients:    runs-on: ubuntu-latest    name: Example    steps:    - uses: actions/checkout@master    - name: Set up Python 3.9      uses: actions/setup-python@v1      with:        python-version: 3.9    - name: Install       run: >-        python -m        pip install -r requirements.txt        --user    - name: Run server in background      run: uvicorn main:app &    - name: Generate OpenAPI document       run: curl localhost:8000/openapi.json > openapi.json    - name: Cleanup old client      run: rm -rf typescript-fetch-client/    - name: Generate new client      uses: openapi-generators/openapitools-generator-action@v1      with:        generator: typescript-fetch    - name: Commit new client      run: |        git config --global user.name 'Your Name'        git config --global user.email '[email protected]'        git add typescript-fetch-client/        git commit -am "Update typescript client"        git push

This action runs on every push and will do the following:

• Setup python
• Install your projects dependencies from the requirements.txt file
• Run our server in the background
• Download our openapi.json file (note: the server starts up very quickly for this example, if yours is slower, you may need to add a sleep or use something like wait-on)
• Use the OpenAPITools Generator action to generate a client. We generated a typescript client based on fetch, but you can create as many clients as you want here.
• Finally, we committed the new client back to our repo. We could have also pushed it to a separate repo, or published it to NPM so others can use it.

And thats all! Now every time anyone makes a change to the API, new clients will automatically be generated to match the API thanks to FastAPIs OpenAPI support. If you want to learn more about FastAPI, check out our related blogs on React + FastAPI Authentication, Dependency Injection with FastAPI's Depends, and RBAC Authorization with FastAPI and PropelAuth.