FastAPI 및 Github 작업으로 클라이언트 자동 생성

API용 javascript/typescript 클라이언트를 직접 작성해 본 적이 있다면 미묘한 버그 작성의 고통을 알고 있을 것입니다. 검색어 매개변수를 놓쳤거나 수정하는 것을 잊은 일부 복사/붙여넣기를 수행했을 수 있습니다. 또는 나중에 API가 변경되어 클라이언트가 업데이트되지 않았을 수도 있습니다. 단순한 실수일 수 있지만 이러한 문제를 디버깅하고 조정하는 것은 팀이 커짐에 따라 악화될 뿐입니다.

OpenAPI + FastAPI를 통한 조정

이 문제에 대한 한 가지 솔루션은 API를 설명하는 JSON 또는 YML을 작성할 수 있는 사양인 OpenAPI입니다. 그러면 클라이언트와 서버가 다른 언어로 되어 있고autogenerate 클라이언트와 서버가 동기화되도록 보장할 수 있습니다.

그러나 이 접근 방식에서 항상 가지고 있던 문제는 내가 만들고 싶은 모든 변경 사항에 대해 OpenAPI 사양을 편집하는 것을 개인적으로 좋아하지 않는다는 것입니다. 프로세스를 더 쉽게 만드는 도구가 있지만 백엔드 개발자로서 저는 백엔드에서 직접 경로를 업데이트하는 것을 선호합니다.

이것이 FastAPI이 들어오는 곳입니다. FastAPI는 많은 사려 깊은 기능을 갖춘 Python 웹 프레임워크입니다. 내가 가장 좋아하는 기능 중 하나는 작성한 코드에서 OpenAPI 사양을 생성한다는 것입니다. 예를 들어 다음 앱을 사용해 보겠습니다.

from typing import Union

from fastapi import FastAPI

app = 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}"}

이것은 하나의 경로, 선택적 쿼리 매개변수 및 JSON 응답이 있는 간단한 앱입니다.

다음으로 서버를 실행합니다.

$ uvicorn main:app

그런 다음 http://localhost:8000/openapi.json 으로 이동하면 API와 일치하는 OpenAPI 사양이 표시됩니다.

API 우선 설계

이렇게 하면 워크플로가 다음에서 변경됩니다.

OpenAPI 스키마 업데이트 ⇒ 서버 경로 생성 ⇒ 클라이언트 생성

에게:

서버 업데이트 ⇒ OpenAPI 스키마 생성 ⇒ 클라이언트 생성

둘 다 장점이 있지만, FastAPI 버전은 내 백엔드를 양호한 상태로 만들고 다른 모든 것이 여기에서 파생되기 때문에 훨씬 더 자연스럽게 느껴집니다.

Github 작업으로 클라이언트 자동 업데이트

API의 클라이언트가 하나만 있는 경우 변경이 필요할 때마다 다시 생성하는 것이 나쁘지 않습니다. 그러나 클라이언트 수가 증가하거나 팀 규모가 증가함에 따라 수동 업데이트에 빠져드는 것을 방지하기 위해 이 프로세스를 자동화하고 싶을 것입니다.

Github Actions을 추가하면 커밋할 때마다 새 클라이언트를 생성할 수 있습니다. 먼저 동작을 살펴본 다음 분석해 보겠습니다.

name: Generate clients
on: push
jobs:
  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

이 작업은 푸시할 때마다 실행되며 다음을 수행합니다.

Python 설정

requirements.txt 파일에서 프로젝트 종속성을 설치합니다

.

백그라운드에서 서버 실행

openapi.json 파일 다운로드

wait-on을 사용하여 클라이언트를 생성합니다. OpenAPITools Generator action을 기반으로 TypeScript 클라이언트를 생성했지만 여기에서 원하는 만큼 클라이언트를 생성할 수 있습니다.

마지막으로 새 클라이언트를 repo에 다시 커밋했습니다. 별도의 리포지토리로 푸시하거나 다른 사람이 사용할 수 있도록 NPM에 게시할 수도 있습니다.

그리고 그게 다야! 이제 누구나 API를 변경할 때마다 FastAPI의 OpenAPI 지원 덕분에 API와 일치하는 새 클라이언트가 자동으로 생성됩니다. FastAPI에 대해 자세히 알아보려면 fetch , React + FastAPI Authentication 및 Dependency Injection with FastAPI's Depends 관련 블로그를 확인하십시오.