FastAPI로 개발하다 보면 API 버전 관리가 필요할 때가 있다.
기본적으로 FastAPI에서는 APIRouter를 사용하여 간단하게 API 버전을 관리할 수 있다.

from fastapi import APIRouter

router_v1 = APIRouter()
router_v2 = APIRouter()

@router_v1.get("/items/")
async def read_items_v1():
    return {"result" : "item v1"}

@router_v2.get("/items/")
async def read_items_v2():
    return {"result" : "item v2"}

위와 같이 APIRouter를 사용하여 버전별로 라우터를 생성하고, 해당 라우터에 API를 등록하면 된다.

from fastapi import FastAPI
from app.api.routes import router_v1, router_v2

app = FastAPI()

app.include_router(router_v1, prefix="/v1")
app.include_router(router_v2, prefix="/v2")

그리고, FastAPI 인스턴스에 include_router 메소드를 사용하여 버전별 라우터를 등록하면 된다.

이렇게 하면 /v1/items/로 요청이 들어오면 read_items_v1 함수가 실행되고, /v2/items/로 요청이 들어오면 read_items_v2 함수가 실행된다.

이런 방법도 좋지만, 다양한 기능을 사용하기 위해서 라이브러리를 사용하는 방법도 존재한다.

기존에는 fastapi-versioning 라이브러리를 사용했지만, 해당 라이브러리는 더 이상 관리되지 않고 있다. 따라서 fastapi-versionizer를 사용하도록 하자.

from fastapi import APIRouter
from fastapi_versionizer.versionizer import api_version

router = APIRouter()

@api_version(1)
@router.get("/items/")
async def read_items_v1():
    return {"result" : "item v1"}

@api_version(2)
@router.get("/items/")
async def read_items_v2():
    return {"result" : "item v2"}

@api_version(1)과 같이 데코레이터를 사용하여 버전을 지정하고, 해당 버전에 맞는 함수를 실행하도록 한다. 이때, 라우터가 중복되어도 버전에 따라 실행되는 함수가 달라진다.

from fastapi import FastAPI, APIRouter
from app.api.routes import router
from fastapi_versionizer.versionizer import Versionizer

app = FastAPI()
api_router = APIRouter()
app.include_router(router)

versions = Versionizer(
    app=app,
    prefix_format="/api/v{major}",
    semantic_version_format="{major}",
    latest_prefix="/api/latest",
    sort_routes=True
).versionize()

기존과 같이 라우터를 등록하고, Versionizer를 추가하여 버전을 관리할 수 있다.

Versionizer에서 사용할 수 있는 매개변수는 다음과 같다.

• app
  • 버전을 관리할 FastAPI 인스턴스
• prefix_format (Default : "/v{major}_{minor}")
  • 경로 접두사를 만들기 위해 사용됨.
  • "{major}" 또는 "{minor}" 또는 함께 사용할 수도 있음.
  • 예: "/v{major}", "/v{major}_{minor}"
• semantic_version_format (Default : "{major}.{minor}")
  • 문서에 표시되는 시맨틱 버전을 만들기 위해 사용됨.
  • 예: "{major}", "{major}.{minor}"
• default_version (Default : (1, 0))
  • @api_version으로 주석이 달려 있지 않은 경우 사용되는 기본 버전
• latest_prefix (Default : None)
  • 최신 버전의 라우트에 대한 별칭 (가장 최신 버전에 대해 추가적으로 생성됨)
  • 예: "latest"
• include_main_docs (Default : True)
  • True인 경우, 모든 버전의 라우트가 포함된 문서 페이지가 생성됨.
• include_main_openapi_route (Default : True)
  • True인 경우, 모든 버전의 라우트가 포함된 OpenAPI 경로가 생성됨.
• include_version_docs (Default : True)
  • True인 경우, 각 버전에 대한 문서 페이지가 생성됨.
• include_version_openapi_route (Default : True)
  • True인 경우, 각 버전에 대한 OpenAPI 경로가 생성됨.
• include_versions_route (Default : False)
  • True인 경우, 모든 API 버전에 대한 정보가 포함된 "GET /versions" 경로가 추가됨.
• sort_routes (Default : False)
  • True인 경우, 모든 라우트의 버전이 오름차순으로 정렬됨.
• callback
  • 각 버전 라우터가 생성되고 모든 라우트가 추가된 후 호출되는 함수
  • 이 함수는 라우터가 루트 FastAPI 앱에 추가되기 전에 호출됨.
  • 이 함수는 아무것도 반환해서는 안 되며 다음과 같은 매개변수를 가짐.
    • 버전 라우터
    • 버전 (튜플 형태)
    • 버전 경로 접두사