FastAPI 베이스캠프

API 문서 살펴보기

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

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

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

2. Swagger UI 살펴보기

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

이전 챕터에서 실행했던 FastAPI 애플리케이션을 실행한 후, 브라우저에서 http://127.0.0.1/docs 경로로 접속합니다.
Swagger UI 화면에서는 다음과 같은 정보를 확인할 수 있습니다.
- 모든 API 엔드포인트 목록
- 목록에 대한 설명(앞서 실습했던 내용)
- 각 엔드포인트의 HTTP 메서드 (GET, POST, PUT, DELETE 등)
- 요청 파라미터 및 본문(body) 스키마
- 응답 스키마
- 인증 방식 (있는 경우)
각 엔드포인트를 클릭하면 상세 정보를 볼 수 있고, "Try it out" 버튼을 통해 API를 직접 테스트할 수 있습니다. 앞서 실습했었던 CRUD 애플리케이션의 API 문서를 Swagger UI로 확인해보겠습니다.

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

3. ReDoc 살펴보기

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

http://127.0.0.1/redoc 경로로 접속합니다.
ReDoc 화면에서는 다음과 같은 정보를 확인할 수 있습니다.
- API의 전체 구조
- 각 엔드포인트의 상세 설명
- 요청 및 응답 스키마
- 모델 정의
ReDoc은 주로 문서 읽기에 최적화되어 있어, API의 전체적인 구조를 파악하기에 좋습니다.

4. API 문서 커스터마이징

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

4.1 API 메타데이터 설정

from fastapi import FastAPI
 
app = FastAPI(
    title="My Super Project",
    description="This is a very fancy project, with auto docs for the API and everything",
    version="2.5.0",
)
 
@app.get("/")
async def root():
    return {"message": "Hello World"}

from fastapi import FastAPI
 
app = FastAPI(
    title="My Super Project",
    description="This is a very fancy project, with auto docs for the API and everything",
    version="2.5.0",
)
 
@app.get("/")
async def root():
    return {"message": "Hello World"}

이렇게 하면 API 문서의 제목, 설명, 버전 등을 설정할 수 있습니다.

4.2 엔드포인트 설명 추가

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/items/", tags=["items"])
async def read_items():
    """
    Retrieve items.
 
    This will use caching for faster responses.
    """
    return [{"item_id": "Foo"}]

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/items/", tags=["items"])
async def read_items():
    """
    Retrieve items.
 
    This will use caching for faster responses.
    """
    return [{"item_id": "Foo"}]

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

4.3 태그 사용하기

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

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]
 
@app.get("/items/", tags=["items"])
async def read_items():
    return [{"item_id": "Foo"}]

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]
 
@app.get("/items/", tags=["items"])
async def read_items():
    return [{"item_id": "Foo"}]

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

연습문제

이전 챕터에서 만든 CRUD 애플리케이션의 API 문서를 커스터마이징해보세요. 제목, 설명, 버전을 추가하고, 각 엔드포인트에 태그와 상세 설명을 붙여보세요.
새로운 엔드포인트를 추가하고, 이에 대한 자세한 설명과 예제 요청/응답을 문서에 포함시켜보세요.
Swagger UI에서 직접 API를 테스트해보고, 결과를 확인해보세요. 어떤 점이 편리하고, 어떤 점이 개선되면 좋을지 생각해보세요.