본문 바로가기

  • 교재 소개

  • 3장 CRUD 애플리케이션 만들기

  • 3.2 API 문서 살펴보기

API 문서 살펴보기

1. FastAPI의 자동 문서화 기능 소개

FastAPI는 OpenAPI(이전의 Swagger) 표준을 기반으로 API 문서를 자동으로 생성합니다. 이 기능은 개발자가 별도의 문서를 작성하지 않아도 API의 구조와 사용법을 쉽게 이해할 수 있게 해줍니다. FastAPI는 API 목록을 확인할 수 있고, 테스트할 수 있는 Swagger UI와 문서를 읽기 쉽게 표현하는 ReDoc 두 가지 유형의 대화형 API 문서를 제공합니다.

문서 유형경로특징
Swagger UI/docsAPI 테스트 가능, 대화형 인터페이스
ReDoc/redoc깔끔한 문서 형태, 읽기에 최적화
OpenAPI JSON/openapi.json위 두 화면을 만들어내는 원본 데이터, JSON 형태의 스키마

셋의 관계는 아래와 같습니다.

/docs와 /redoc은 /openapi.json을 읽어서 그려낸 화면일 뿐입니다. 이 구조가 중요한 이유는 마지막 두 갈래에 있습니다. openapi.json은 표준 형식이라 다른 도구도 읽을 수 있습니다.

Swagger UI는 FastAPI에서만 사용하는 것이 아니라, 다양한 백엔드 프레임워크에서도 사용하기 때문에 다양한 개발자에게 친숙한 환경입니다. 프론트엔드와 협업할 때에도 API 문서를 공유하면서 개발을 진행하기 수월할 것입니다.

2. Swagger UI 살펴보기

Swagger UI는 API를 시각적으로 표현하고 직접 테스트할 수 있는 환경을 제공합니다.

  1. 이전 챕터에서 실행했던 FastAPI 애플리케이션을 실행한 후, 브라우저에서 http://127.0.0.1:8000/docs 경로로 접속합니다.

  2. Swagger UI 화면에서는 다음과 같은 정보를 확인할 수 있습니다.

    • 모든 API 엔드포인트 목록
    • 목록에 대한 설명(코드에 적은 summary와 docstring)
    • 각 엔드포인트의 HTTP 메서드 (GET, POST, PATCH, DELETE 등)
    • 요청 파라미터 및 본문(body) 스키마
    • 응답 스키마와 상태 코드
    • 인증 방식 (있는 경우)

  3. 각 엔드포인트를 클릭하면 상세 정보를 볼 수 있고, "Try it out" 버튼을 통해 API를 직접 테스트할 수 있습니다. 앞서 실습했었던 CRUD 애플리케이션의 API 문서를 Swagger UI로 확인해보겠습니다.

    아래와 같이 메서드를 클릭해 입력하는 것으로 API를 테스트할 수 있습니다. 안에 들어가는 값도 자동으로 생성되어 있으며 수정하여 테스트할 수 있습니다.

앞 절의 CRUD 코드로 아래 순서를 직접 해보세요.

  1. POST /items를 펼치고 Try it out을 누릅니다.
  2. Request body에 예시 값이 채워져 있습니다. 값을 바꾸고 Execute를 누릅니다.
  3. 아래에 Response body와 상태 코드가 나타납니다. 201이 맞는지 확인합니다.
  4. Curl 항목에 방금 보낸 요청이 curl 명령어 형태로도 표시됩니다. 이 명령어는 터미널에 그대로 붙여넣어 실행할 수 있습니다.

4번을 알아두면 유용합니다. 서버에 접속해서 확인해야 할 때, 이 명령어를 복사해 쓰면 됩니다.

3. ReDoc 살펴보기

ReDoc은 Swagger UI보다 더 깔끔하고 읽기 쉬운 형태로 API 문서를 제공합니다.

  1. http://127.0.0.1:8000/redoc 경로로 접속합니다.

  2. ReDoc 화면에서는 다음과 같은 정보를 확인할 수 있습니다.

    • API의 전체 구조
    • 각 엔드포인트의 상세 설명
    • 요청 및 응답 스키마
    • 모델 정의

  3. ReDoc은 주로 문서 읽기에 최적화되어 있어, API의 전체적인 구조를 파악하기에 좋습니다.

Swagger UI는 실행 버튼이 있어 테스트에 좋고, ReDoc은 왼쪽에 목차가 있어 읽기에 좋습니다. 프론트엔드 개발자에게 문서를 전달할 때는 ReDoc 주소를, 직접 테스트해봐야 할 때는 Swagger UI 주소를 주면 됩니다.

4. API 문서 커스터마이징

FastAPI에서는 API 문서를 커스터마이징할 수 있습니다. 몇 가지 기본적인 방법을 살펴보겠습니다.

4.1 API 메타데이터 설정

from fastapi import FastAPI

app = FastAPI(
    title="위니브 물품 관리 API",
    description="""
FastAPI 베이스캠프 3장에서 만든 물품 관리 API입니다.

## 기능

* 물품 등록, 조회, 수정, 삭제
* 이름으로 검색
""",
    version="1.0.0",
    contact={"name": "위니브", "url": "https://weniv.co.kr"},
)

이렇게 하면 API 문서의 제목, 설명, 버전 등을 설정할 수 있습니다. description에는 마크다운을 쓸 수 있습니다. 문서 맨 위에 그대로 렌더링됩니다.

4.2 엔드포인트 설명 추가

함수의 docstring을 사용하여 각 엔드포인트에 대한 자세한 설명을 추가할 수 있습니다.

@app.get("/items", tags=["물품"], summary="물품 목록 조회")
async def read_items() -> list[Item]:
    """
    등록된 모든 물품을 반환합니다.

    - 정렬 순서는 등록순입니다.
    - 아직 페이지네이션이 없어 전체를 한 번에 반환합니다.
    """
    return list(items.values())
항목문서에서 보이는 위치
summary엔드포인트 목록에 한 줄로 표시
docstring엔드포인트를 펼쳤을 때 나오는 설명, 마크다운 사용 가능

4.3 태그 사용하기

태그를 사용하면 API 엔드포인트를 그룹화할 수 있습니다.

from fastapi import FastAPI

app = FastAPI()


@app.get("/users", tags=["사용자"])
async def read_users():
    return [{"username": "licat"}]


@app.get("/items", tags=["물품"])
async def read_items():
    return [{"item_id": "Foo"}]

이렇게 하면 Swagger UI와 ReDoc에서 엔드포인트가 태그별로 그룹화되어 표시됩니다. 그룹화된 엔드포인트는 127.0.0.1:8000/docs 나 127.0.0.1:8000/redoc 에서 그룹별로 확인할 수 있습니다. 엔드포인트가 20개, 30개로 늘어나면 태그 없이는 문서를 읽기 어렵습니다.

태그에 설명을 붙일 수도 있습니다.

app = FastAPI(
    openapi_tags=[
        {"name": "물품", "description": "물품을 등록하고 관리합니다."},
        {"name": "사용자", "description": "회원가입과 로그인을 처리합니다."},
    ]
)

4.4 예시 값 지정하기

Swagger UI가 자동으로 채워주는 예시 값은 string, 0 같은 무의미한 값입니다. 실제로 넣어볼 만한 값을 지정하면 테스트가 훨씬 편해집니다.

from pydantic import BaseModel, Field


class ItemCreate(BaseModel):
    name: str = Field(min_length=1, max_length=50, examples=["기계식 키보드"])
    description: str | None = Field(default=None, examples=["적축, 텐키리스"])
    price: float = Field(ge=0, examples=[129000])

Try it out을 눌렀을 때 이 값들이 미리 채워집니다. 팀원이 API를 처음 볼 때 무엇을 넣어야 할지 바로 알 수 있습니다.

5. OpenAPI JSON 활용하기

http://127.0.0.1:8000/openapi.json에 접속하면 API 전체 정보가 JSON으로 나옵니다. 브라우저에서 보면 한 줄로 붙어 있어 읽기 어렵지만, 이 데이터는 사람이 읽으라고 있는 것이 아닙니다.

이 파일로 할 수 있는 일이 여럿 있습니다.

  1. 프론트엔드 코드 자동 생성: OpenAPI 문서를 읽어 TypeScript 타입과 API 호출 함수를 만들어주는 도구들이 있습니다. 백엔드에서 필드 이름을 바꾸면 프론트엔드 타입도 자동으로 바뀝니다.
  2. AI 도구에 컨텍스트 제공: AI에게 "이 API를 호출하는 화면을 만들어줘"라고 할 때, openapi.json을 함께 주면 추측 없이 정확한 필드명으로 코드를 만들어냅니다.
  3. API 변경 감지: 배포 전후의 openapi.json을 비교하면 의도치 않게 API가 바뀌었는지 확인할 수 있습니다.

파일로 저장하려면 아래 명령을 사용합니다.

curl http://127.0.0.1:8000/openapi.json -o openapi.json

6. 실서비스에서 문서 감추기

문서가 자동으로 만들어지는 것은 편리하지만, 외부에 공개된 서버라면 문제가 될 수 있습니다. API 목록과 요청 형식이 그대로 노출되기 때문입니다. 문서를 끄려면 None을 지정합니다.

app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

경로를 바꿔서 짐작하기 어렵게 만들 수도 있습니다.

app = FastAPI(docs_url="/internal-docs", redoc_url=None)

다만 이 방법은 경로를 아는 사람은 여전히 볼 수 있으므로 완전한 보안 수단은 아닙니다. 환경에 따라 켜고 끄는 방법은 7장 설정 관리에서 다룹니다.

개발 환경에서는 켜두세요

문서를 끄면 Try it out도 사라져 개발이 불편해집니다. 실습 중에는 그대로 두고, 실제로 배포할 때만 고려하시면 됩니다.

연습문제

  1. 이전 챕터에서 만든 CRUD 애플리케이션의 API 문서를 커스터마이징해보세요. 제목, 설명, 버전을 추가하고, 각 엔드포인트에 태그와 summary, docstring을 붙여보세요.

  2. ItemCreate 모델의 각 필드에 examples를 지정하고, Swagger UI의 Try it out에서 어떻게 보이는지 확인해보세요.

  3. openapi.json을 파일로 저장한 뒤 열어보세요. paths, components 두 항목이 각각 무엇을 담고 있는지 확인해보세요.

  4. Swagger UI에서 직접 API를 테스트해보고, 화면에 표시된 curl 명령어를 복사해 터미널에서 실행해보세요. 같은 결과가 나오는지 확인하고, 어떤 점이 편리하고 어떤 점이 개선되면 좋을지 생각해보세요.

API 문서 살펴보기 - FastAPI 베이스캠프 | 위니버시티