/docs 하나로 협업하기 — Swagger UI·ReDoc·OpenAPI 제대로 쓰는 법 (FastAPI 입문 3편)

{
  "tags": ["할 일"],
  "summary": "할 일 만들기",
  "description": "새 할 일을 만든다.\n\n- **title**: 1~100자, 필수\n- **priority**: 1~5, 생략하면 3",
  "operationId": "create_task_tasks_post",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } }
    }
  },
  "responses": {
    "201": { "description": "만들어진 할 일" },
    "422": { "description": "Validation Error" }
  }
}

npx openapi-typescript http://127.0.0.1:8000/openapi.json -o src/api.d.ts

TaskCreate: {
    /**
     * Title
     * @description 할 일 제목
     * @example 보고서 초안 쓰기
     */
    title: string;
    // ...
};

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

tags_metadata = [
    {"name": "할 일", "description": "할 일을 만들고, 보고, 고치고, 지운다."},
    {"name": "운영", "description": "서버 상태 확인용. 프론트엔드는 쓰지 않는다."},
]

app = FastAPI(
    title="할 일 API",
    version="1.0.0",
    description="""
팀 공용 **할 일 관리 API**입니다.

* 모든 시간은 한국 시간(KST)입니다.
* 문의: 백엔드 채널 `#team-backend`
""",
    openapi_tags=tags_metadata,
)


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=100, description="할 일 제목", examples=["보고서 초안 쓰기"])
    priority: int = Field(default=3, ge=1, le=5, description="1(낮음) ~ 5(높음)", examples=[4])


class Task(BaseModel):
    id: int
    title: str
    priority: int
    done: bool


class Message(BaseModel):
    detail: str


tasks: dict[int, Task] = {}


@app.post(
    "/tasks",
    response_model=Task,
    status_code=status.HTTP_201_CREATED,
    tags=["할 일"],
    summary="할 일 만들기",
    response_description="만들어진 할 일",
)
def create_task(payload: TaskCreate):
    """
    새 할 일을 만든다.

    - **title**: 1~100자, 필수
    - **priority**: 1~5, 생략하면 3
    """
    task = Task(id=len(tasks) + 1, done=False, **payload.model_dump())
    tasks[task.id] = task
    return task


@app.get("/tasks", response_model=list[Task], tags=["할 일"], summary="할 일 목록")
def list_tasks(done: bool | None = None):
    return [t for t in tasks.values() if done is None or t.done == done]


@app.get(
    "/tasks/{task_id}",
    response_model=Task,
    tags=["할 일"],
    summary="할 일 하나 보기",
    responses={404: {"model": Message, "description": "그 번호의 할 일이 없음"}},
)
def read_task(task_id: int):
    if task_id not in tasks:
        raise HTTPException(status_code=404, detail=f"{task_id}번 할 일이 없습니다")
    return tasks[task_id]


@app.get("/todos", tags=["할 일"], summary="(구버전) 할 일 목록", deprecated=True)
def list_todos_old():
    return list(tasks.values())


@app.get("/health", tags=["운영"], summary="서버 상태 확인")
def health():
    return {"status": "ok"}


@app.get("/internal/debug", include_in_schema=False)
def debug():
    return {"tasks": len(tasks)}

import os

from fastapi import FastAPI

IS_PROD = os.getenv("APP_ENV") == "production"

app = FastAPI(
    title="할 일 API",
    docs_url=None if IS_PROD else "/docs",
    redoc_url=None if IS_PROD else "/redoc",
    openapi_url=None if IS_PROD else "/openapi.json",
)