Generating FastAPI client code with GitHub Action.

[synchronizing]

Creating microservices is hard enough... creating boilerplate code to call your microservices from other microservices is just plain annoying. Sharing a quick and easy way to automate the generation of client code utilizing GitHub actions for anyone that might have use for it.

Using the FastAPI code example given here, we will have GitHub automatically generate the OpenAPI client code in a separate branch called client using OpenAPI Generator. This is the current project structure (GitHub link to project can be found here):

fastapi-gh-action-example
├── .github
│   └── workflows
│       └── generate-client.yml
├── README.md
├── fast
│   ├── __init__.py
│   └── main.py
├── openapirc.yaml
└── requirements.txt

requirements.txt

fastapi

openapirc.yaml

packageName: fastapi_gh
projectName: FastAPI Client Generation with Github Action Example

main.py

The function at the bottom will rename the operationId configuration of the OpenAPI to that of the Python function name. Makes the function calls easier to read. Relevant docs can be found here.

from typing import Optional
from fastapi import FastAPI
from fastapi.routing import APIRoute

app = FastAPI(
    title="Fast",
    version=1,
    description="FastAPI example with GitHub Action to generate client code.",
)

@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

# Modifies the operation_id OpenAPI variable for the function name.
for route in app.routes:
    if isinstance(route, APIRoute):
        route.operation_id = route.name

generate-client.yml

The relevant piece of code. Documentation for each step of the GitHub action can be found below.

name: Generate Client

# Runs this action whenever there are any changes to the master branch.
on:
  push:
    branches:
      - master

jobs:
  client:
    runs-on: ubuntu-latest

    # Checks out the entire repo.
    steps:
    - name: Checks out repo
      uses: actions/checkout@v1

    # Generates a openapi.yaml file based on the FastAPI project.
    - name: Generate OpenAPI file
      uses: column-street/fastapi-openapi-specs-action@v1.0.0
      with:
        moduleDir: fast
        fileName: main.py
        appName: app

    # Uses an external tool, openapitools-generator-action, to generate the client code.
    # The 'openapirc.json' file is the following: { "packageName": "fast", "projectName": "fast" }
    # and it lives inside the master branch of the repository. Comamnd outputs a new folder called 
    # 'python-client' with the relevant client code.
    - name: Generate Python Client
      uses: triaxtec/openapitools-generator-action@v1.0.0
      with:
        generator: python
        openapi-file: openapi.yaml
        config-file: openapirc.yaml

    # Deletes every file in the folder, except '.git' and the new generated 'python-client' folder.
    # Moves all content of the 'python-client' folder to the root directory.
    - name: Cleans the branch up.
      run: |
        # Removes all files except the .git and python-client folder.
        shopt -s extglob
        sudo rm -rf !(.|..|.git|python-client)
        # Moves all of the content of the python-client folder out, 
        # and deletes the folder.
        mv python-client/* .
        rm -rf python-client

    # Commits the new changes into a new branch called 'client'.
    - name: Commit changes.
      run: |
        git checkout -b client 
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add .
        git commit -m "Generated client." -a || true 

    # Pushes all of these changes into the GitHub repository.
    - name: Push changes to client branch
      uses: ad-m/github-push-action@master
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        branch: client
        force: True

Once .github/workflows/generate-client.yml file is added to your repo and modified for your use case it should automatically auto-generate your FastAPI client code into a branch client (unless changed).

Example

• master: https://github.com/synchronizing/fastapi-gh-action-example
• client: https://github.com/synchronizing/fastapi-gh-action-example/tree/client
• Action: https://github.com/synchronizing/fastapi-gh-action-example/actions

Relevant Documentation

• OpenAPI Generator
• openapitools-generator-action
• fastapi-openapi-specs-action