FastAPI와 OpenAPI를 이용한 API 문서 자동 생성

 

FastAPI는 Python으로 작성된 빠르고 현대적인 웹 프레임워크입니다. OpenAPI는 웹 서비스 API를 설계하고 문서화하기 위한 일반적으로 사용되는 형식 중 하나입니다.

FastAPI는 OpenAPI를 기본적으로 지원하며, 이를 통해 API 문서 자동 생성이 가능합니다. FastAPI는 Swagger UI 및 ReDoc과 같은 도구를 사용하여 API 문서를 자동 생성합니다. Swagger UI는 API 요청 및 응답을 시각화하고, ReDoc는 API 문서를 미려하게 보여줍니다.

API 문서를 자동 생성하려면 먼저 FastAPI 프로젝트에서 OpenAPI 스키마를 정의해야 합니다. 이는 FastAPI의 데코레이터 및 파라미터로 수행됩니다. FastAPI는 이러한 정보를 사용하여 API 문서를 자동 생성합니다.

예를 들어, FastAPI에서는 다음과 같이 API 엔드포인트를 정의할 수 있습니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

 

위 코드에서 @app.get 데코레이터는 GET 요청을 처리하는 엔드포인트를 정의합니다. {item_id}와 같은 경로 매개변수 및 q와 같은 쿼리 매개변수는 FastAPI에 의해 자동으로 문서화됩니다.

이제 API 문서를 생성하려면 FastAPI 프로젝트를 실행하고 /docs 또는 /redoc 엔드포인트로 이동하면 됩니다. 이를 통해 Swagger UI 또는 ReDoc를 사용하여 API 문서를 볼 수 있습니다.

이처럼 FastAPI와 OpenAPI를 이용하여 API 문서를 자동으로 생성할 수 있습니다. 이를 통해 개발자는 API를 쉽게 이해하고 사용할 수 있으며, 개발자들은 API 문서 작성에 드는 시간과 노력을 줄일 수 있습니다.

 

API 문서 자동 생성은 API 개발자 및 사용자 모두에게 매우 유용합니다. 개발자는 API 엔드포인트, 매개변수 및 요청/응답 형식에 대한 정보를 쉽게 이해할 수 있으며, 이를 통해 개발 시간을 단축할 수 있습니다. 또한, 사용자는 API를 더 쉽게 이해하고 사용할 수 있으며, API 변경 사항에 대한 업데이트를 더 쉽게 파악할 수 있습니다.

API 문서 자동 생성은 FastAPI 외에도 다른 웹 프레임워크에서도 가능합니다. 예를 들어, Flask는 Flask-RESTful 또는 Flask-RESTX와 같은 확장 기능을 사용하여 API 문서를 자동 생성할 수 있습니다.

그리고 API 문서 자동 생성 이외에도 OpenAPI를 사용하여 API를 설계하고 문서화할 수 있습니다. OpenAPI를 사용하면 API 요청 및 응답에 대한 표준 형식을 정의할 수 있으며, 이를 통해 API 구현에 대한 일관성을 유지할 수 있습니다. 또한, OpenAPI를 사용하면 API 클라이언트를 생성하는 도구를 사용하여 API를 사용하는 데 필요한 코드를 자동으로 생성할 수 있습니다.

API 문서 자동 생성 및 OpenAPI를 사용하는 것은 현대적인 웹 개발에서 매우 중요한 요소입니다. 이를 통해 API 사용자와 개발자 모두가 더 나은 사용자 경험을 얻을 수 있으며, API를 더 쉽게 사용할 수 있습니다.

 

보안 설정

FastAPI에서 /docs와 /redoc에 특정 IP만 접근하도록 설정하려면, /docs와 /redoc의 URL 경로를 각각 docs_url=None 및 redoc_url=None으로 설정하고, 미들웨어를 사용하여 특정 IP에서만 해당 URL에 접근할 수 있도록 구성해야 합니다.

다음은 FastAPI에서 /docs와 /redoc에 특정 IP만 접근할 수 있도록 구성하는 예제입니다.

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import re

app = FastAPI()

@app.middleware("http")
async def check_ip(request: Request, call_next):
    if request.url.path not in ["/docs", "/redoc"]:
        return await call_next(request)
    
    origin_ip = None
    x = 'x-forwarded-for'.encode('utf-8')
    for header in request.headers.raw:
        if header[0] == x:
            origin_ip, forward_ip = re.split(', ', header[1].decode('utf-8'))
    
    allowed_ips = ["127.0.0.1", "192.168.1.1"]
    if origin_ip not in allowed_ips:
        return JSONResponse(content={"message": "Not allowed"}, status_code=403)
    response = await call_next(request)
    return response

 

위 코드에서 FastAPI(docs_url=None, redoc_url=None)은 /docs 및 /redoc 엔드포인트를 비활성화합니다. 미들웨어 check_ip는 모든 HTTP 요청에 대해 호출됩니다. 먼저 allowed_ips 변수에 허용된 IP 주소를 나열합니다. 그런 다음, 요청 경로가 /docs 또는 /redoc이고 클라이언트 IP가 allowed_ips에 포함되어 있지 않은 경우, JSONResponse를 반환하여 403 Forbidden 오류를 표시합니다. 그렇지 않으면 요청을 처리합니다.