기타 (Other)

[python] FastAPI

Kim MyeongOk 2025. 2. 11. 21:43

document page) FastAPI | 메타데이터 및 문서화 URL

 

FastAPI는 웹 애플리케이션을 빠르고 쉽게 만들 수 있는 프레임워크로, 자동 문서화 기능이 매우 강력함. FastAPI는 기본적으로 OpenAPI와 JSON Schema를 기반으로 API의 메타데이터와 자동화된 문서화를 생성하는 기능을 제공함. 이로 인해 API를 개발할 때, 자동으로 Swagger UI와 ReDoc을 통해 문서를 제공할 수 있음.

1. FastAPI의 메타데이터 및 문서화 기본 개념

FastAPI는 다음 두 가지를 통해 API의 메타데이터와 문서화를 제공합니다:

  • OpenAPI: FastAPI는 OpenAPI 스펙을 자동으로 생성하여 API 문서를 제공합니다.
  • JSON Schema: FastAPI는 Pydantic 모델을 사용하여 JSON Schema를 기반으로 자동으로 입력 값과 반환 값을 검증하고 문서화합니다.

2. FastAPI에서 기본 문서화 활성화

FastAPI는 Swagger UI와 ReDoc을 기본적으로 지원합니다. API 서버를 실행하면 두 가지 문서화 방법에 접근할 수 있습니다.

  • Swagger UI: API 문서를 시각적으로 보여주는 UI (기본 경로: /docs)
  • ReDoc: 깔끔하고 읽기 쉬운 문서 (기본 경로: /redoc)

FastAPI 앱을 작성하고 실행하면, 두 가지 문서를 자동으로 생성해줌.

예시: 기본 FastAPI 애플리케이션

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "price": item.price}
이 코드를 실행하면, FastAPI는 http://127.0.0.1:8000/docs경로에서 Swagger UI를 제공하고, http://127.0.0.1:8000/redoc경로에서 ReDoc 문서를 제공함.

3. FastAPI에서 메타데이터 추가

FastAPI 애플리케이션에 메타데이터를 추가하여 문서화 정보를 더 구체적으로 제공할 수 있음. 예를 들어, API 제목, 설명, 버전 등을 명시할 수 있음.

예시: FastAPI 메타데이터 추가

from fastapi import FastAPI

app = FastAPI(
    title="My API",  # API 제목
    description="This is a detailed description of the API.",  # API 설명
    version="1.0.0",  # API 버전
    contact={
        "name": "API Support",
        "url": "https://example.com",
        "email": "support@example.com"
    }
)

@app.get("/")
async def read_root():
    return {"message": "Welcome to the API"}

이렇게 하면 Swagger UI나 ReDoc에서 메타데이터가 반영되어 표시됨.

4. FastAPI에서 Path Parameters, Query Parameters, Request Body 문서화

FastAPI는 요청 파라미터, 경로 파라미터, 요청 본문을 자동으로 문서화함. 이를 통해 API 사용자는 무엇을 입력해야 하는지 쉽게 알 수 있음.

예시: Path Parameters, Query Parameters, Request Body 문서화

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float

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

@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "price": item.price}
이 예시에서는:
  • Path Parameter (item_id)와 Query Parameter (q)가 문서화됨.
  • Request Body (Item 모델)는 자동으로 문서화됨.

5. 문서화에서 추가적인 메타데이터 사용 (Optional, Default Value 등)

FastAPI는 Pydantic 모델을 사용해 데이터 검증을 하며, 모델의 필드에 optional하거나 기본값을 설정할 수 있음. 이 내용도 자동으로 문서화됨.

예시: Optional, Default Value 설정

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None  # Optional 필드
    price: float
    tax: Optional[float] = 10.0  # 기본값 설정

@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "price": item.price, "tax": item.tax}​

이 예시에서:

  • description은 Optional 필드로 문서화됨.
  • tax는 기본값으로 10.0을 가지며, 문서화에서 기본값을 자동으로 보여줌.

6. FastAPI에서 Response 모델 문서화

FastAPI는 응답 모델을 문서화할 때도 유용함. response_model을 사용하여 반환값을 정의할 수 있음. 이로 인해, 반환값도 자동으로 문서화됨.

예시: Response 모델 문서화

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str = None
    price: float

class ItemResponse(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=ItemResponse)
async def create_item(item: Item):
    return {"name": item.name, "price": item.price}​

이 예시에서는 response_model을 사용하여 반환되는 데이터의 형식을 정의하고, 이를 자동으로 문서화할 수 있음.

7. FastAPI에서 사용자 정의 문서화 (예: 설명 추가, 데코레이터 사용)

FastAPI는 문서화 시 설명을 더 추가하거나, 메소드, 파라미터 등을 더 구체적으로 설명할 수 있음. description, summary 등을 사용하여 문서에 추가적인 정보를 제공할 수 있음.

예시: 상세한 문서화 추가

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def get_item(
    item_id: int = Query(..., description="The ID of the item to get")
):
    """
    This API endpoint returns an item by its ID.
    - **item_id**: The ID of the item (required).
    """
    return {"item_id": item_id}​

이 예시에서는 Query(..., description="..."를 사용하여 파라미터에 대한 설명을 추가하였고, """을 사용하여 API 엔드포인트에 추가적인 설명을 제공함.

결론

  • FastAPI는 OpenAPI와 JSON Schema를 사용하여 자동으로 API 문서화를 생성함.
  • Swagger UI와 ReDoc을 통해 자동으로 API 문서를 제공하며, FastAPI는 메타데이터 (API 제목, 설명, 버전 등) 및 요청/응답에 대한 세부 정보를 자동으로 문서화함.
  • Path Parameters, Query Parameters, Request Body, Response 모델 등도 자동으로 문서화되며, 추가적인 설명을 description, summary 등으로 쉽게 추가할 수 있음.

이러한 기능을 통해 FastAPI는 자동화된 문서화를 통해 개발자가 API 문서를 쉽게 유지 보수하고, 사용자에게 직관적인 문서를 제공할 수 있게 돕는 강력한 도구임.