1. tags: 엔드포인트 분류
tags는 엔드포인트를 분류하고 그룹화하여 API 문서에서 관련 엔드포인트를 함께 표시하는 데 사용된다. 태그를 사용하면 API 문서가 더 구조적이고 탐색하기 쉬워진다.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", tags=["items"])
def get_items():
return {"items": ["item1", "item2"]}
@app.get("/users/", tags=["users"])
def get_users():
return {"users": ["user1", "user2"]}여기서는 items와 users라는 태그를 사용하여 엔드포인트를 분류한다. Swagger UI와 ReDoc에서 이 태그를 통해 엔드포인트를 쉽게 탐색할 수 있다.
2. summary: 간단한 설명
summary는 엔드포인트의 기능을 간략하게 설명하는 데 사용된다. 이는 API 문서에서 각 엔드포인트의 목적을 빠르게 이해하는 데 도움이 된다.
from fastapi import FastAPI
app = FastAPI()
@app.get(
"/items/",
tags=["items"],
summary="item 목록을 조회한다.",
)
def get_items():
return {"items": ["item1", "item2"]}summary는 엔드포인트가 어떤 작업을 수행하는지 간단하게 설명한다. 이 정보는 Swagger UI의 엔드포인트 목록에서 쉽게 확인할 수 있다.
3. description: 상세 설명
description은 엔드포인트의 기능에 대해 더 자세한 설명을 제공하는 데 사용된다. 이 설명은 API 문서에서 엔드포인트에 대한 더 많은 배경 정보를 제공한다.
from fastapi import FastAPI
app = FastAPI()
@app.get(
"/items/",
tags=["items"],
summary="item 목록을 조회한다.",
description="이 API는 모든 사용가능한 item 목록을 조회한다. 그리고 페이징과 필터링을 지원한다.",
)
def get_items():
return {"items": ["item1", "item2"]}description은 Swagger UI와 ReDoc의 엔드포인트 세부 정보에서 확인할 수 있다.
4. docstring: 엔드포인트의 주석
FastAPI는 엔드포인트 함수의 docstring을 사용하여 API 문서에 설명을 추가할 수 있다. 이 설명은 description과 함께 엔드포인트의 상세 정보를 제공한다.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
def get_items():
"""
Retrieve a list of items.
This endpoint retrieves a list of all available items in the inventory.
It supports pagination and filtering.
"""
return {"items": ["item1", "item2"]}여기서는 get_items 함수의 docstring을 사용하여 엔드포인트의 상세 설명을 추가했다. 이 설명은 FastAPI 문서에 포함된다.
description과 docstring이 둘 다 있는 경우는 description이 우선한다.
5. response_description: 응답 설명
response_description은 응답의 내용을 설명하는 데 사용된다. 이 설명은 Swagger UI와 ReDoc에서 응답의 구조와 내용을 이해하는 데 도움이 된다.
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str
@app.get("/items/", response_description="모든 item 목록")
def get_items():
return {
"items": [
{"name": "item1", "description": "샘플 아이템"},
{"name": "item2", "description": "또 다른 샘플 아이템"},
]
}여기서는 response_description을 사용하여 응답 데이터의 내용을 설명한다.
6. deprecated: 사용 중단된 엔드포인트
deprecated는 특정 엔드포인트가 더 이상 사용되지 않음을 나타내는 데 사용된다. 이를 통해 클라이언트는 해당 엔드포인트가 곧 제거될 수 있음을 알 수 있다.
from fastapi import FastAPI
app = FastAPI()
@app.get("/old-endpoint/", deprecated=True, summary="삭제될 예정입니다.")
def old_endpoint():
return {"message": "This endpoint is deprecated and will be removed in future versions."}deprecated=True로 설정하면 해당 엔드포인트가 문서에 deprecated로 표시되며, 클라이언트에게 사용 중단된 엔드포인트임을 알릴 수 있다.
