FastAPI docs 작성 방법 정리

Python의 fastapi를 통하여 API 문서를 자동으로 쉽게 작성되도록 만들 수 있습니다.

이 기능을 잘 활용하면 API를 구현할 때 이점이 굉장히 많은데요.

이번 글에서는 fastapi의 docs 작성 방법들에 대하여 간략하게 요약해보도록 하겠습니다.

 

 

텍스트 설명 입력 방법

API 사용 방법에 대하여 텍스트 설명을 추가하고 싶은 경우가 많습니다.

여기서는 3가지 방법을 소개합니다.

summary: 메소드 사용 방법 옆의 설명(빨간색 표시 부분)

description: 메소드 상세 사용 방법(주황색 표시 부분)

response_description: response 메시지에 관한 설명(노란색 표시 부분)

 

위 3가지 설명란이 제공된 docs의 예시는 다음과 같습니다.

 

코드에서는 위 3가지를 다음과 같이 적용할 수 있습니다.

description의 경우에는 아래 예시처럼 docstring으로 명시해주면 편리합니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}", summary="item id 조회", response_description="원하는 아이템을 찾습니다.")
async def read_item(item_id: int):
    """
    item id를 조회하는 엔드포인트입니다.
    - **item_id**: 찾으려는 item의 id
    """
    return {"item_id": item_id}

 

 

파라미터 설명 입력 방법

각 파라미터에도 설명을 입력하여 docs에서 보이도록 만들 수 있습니다.

또한, alias를 지정하여 docs에서 다른 이름으로 보이도록 지정하는 것도 가능합니다.

 

alias 및 설명을 지정하는 간단한 코드 및 docs 예시는 다음과 같습니다.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(
    item_id: int,
    q: str = Query(None, alias="item-query", description="Query string for the items to search in the database")
):
    return {"item_id": item_id, "q": q}

 

 

또한, 의존성 주입 기능을 활용하면 파라미터 설명을 쉽게 추가하는 것이 가능합니다.

이를 활용한 예시는 다음과 같이 정리해볼 수 있습니다.

from fastapi import FastAPI, Depends

app = FastAPI()

def common_parameters(q: str = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items/")
async def read_items(commons: dict = Depends(common_parameters)):
    return commons

 

 

 

Request Body 입력 방법

input에 해당하는 request body의 양식을 docs를 통해서 알려주기 위해서는

pydantic의 데이터 모델 기능을 활용하시면 됩니다.

함수의 input 부분에 해당 타입을 명시해주시면 됩니다.

 

코드 및 적용된 docs의 예시는 다음과 같습니다.

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 item

 

 

 

Response Model 입력 방법

output에 해당하는 response model도 마찬가지로 데이터 모델을 통하여

지정이 가능합니다. 코드에서 response_model 인자를 명시해주시면 됩니다.

 

코드 및 문서의 예시는 다음과 같습니다.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    return {"name": f"{item_id}번 아이템", "price": 1000, "description": "아이템 예시", "tax": 100}

 

 

 

API 문서 제목, 설명, 버전 입력 방법

API 문서의 제목, 설명, 버전 등의 정보를 커스텀하고 싶다면

app 선언 시에 인자로 명시해주시면 됩니다.

app = FastAPI(
    title="My API",
    description="API 설명 예시입니다.",
    version="0.1.5"
)

 

 

여기까지 제 글을 잘 봐주셔서 대단히 감사드립니다.

이 내용들이 조금이라도 도움이 되셨기를 빌며, 좋은 하루 보내시길 기원하겠습니다.