FastAPI에서 문서 접속을 환경설정으로 제한하는 방법

FastAPI에서 문서 접속을 환경설정으로 제한하는 방법

FastAPI에서 문서 접속을 환경설정으로 제한하는 방법

🌐 FastAPI에서 문서 접속을 환경설정으로 제한하는 방법

FastAPI는 기본적으로 /docs, /redoc, /openapi.json 경로에 API 문서를 자동으로 제공합니다. 하지만 운영 환경에서는 보안상 이 문서들을 비활성화하는 것이 좋습니다. 이 글에서는 .env 파일과 python-dotenv를 사용해 환경에 따라 문서 기능을 자동으로 제어하는 방법을 설명합니다.

✅ 1. python-dotenv 설치

.env 파일을 로드하려면 python-dotenv 패키지가 필요합니다.

pip install python-dotenv

✅ 2. 디렉토리 구조 예시

.
├── main.py
└── .env

✅ 3. .env 파일 작성

운영/개발 환경을 설정합니다.

# .env
ENV=production

개발 시에는 ENV=development로 변경하면 됩니다.

✅ 4. main.py 코드

dotenv로 환경변수를 불러온 뒤, FastAPI 인스턴스를 조건부로 구성합니다.

# main.py
import os
from fastapi import FastAPI
from dotenv import load_dotenv

# .env 파일 로드
load_dotenv()

# 운영 환경 여부 판단
ENV = os.getenv("ENV", "development")
IS_PROD = ENV == "production"

# FastAPI 앱 생성 (문서 비활성화 여부 설정)
app = FastAPI(
    title="My App",
    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"
)

# 예시 라우터
@app.get("/hello")
def read_root():
    return {"message": "Hello World"}

✅ 5. 실행 방법

📦 개발 환경 (문서 활성화)

ENV=development uvicorn main:app --reload

또는 .env에서 ENV=development로 설정하고:

uvicorn main:app --reload

🔐 운영 환경 (문서 비활성화)

ENV=production uvicorn main:app

또는 .env에서 ENV=production 설정 후:

uvicorn main:app

이제 /docs, /redoc, /openapi.json 경로는 운영 환경에서 접근되지 않습니다.

🔍 참고: FastAPI 문서 관련 옵션

옵션	설명
docs_url	Swagger UI URL (기본: /docs)
redoc_url	ReDoc 문서 URL (기본: /redoc)
openapi_url	OpenAPI 스펙 JSON 경로 (기본: /openapi.json)

이들을 None으로 설정하면 해당 기능이 완전히 비활성화됩니다.

✅ 마무리

.env 파일과 load_dotenv()를 사용하면 운영/개발 환경에 따라 FastAPI 문서 접근을 쉽게 제어할 수 있습니다. 문서를 완전히 끄거나 인증 보호를 추가하고 싶다면 별도로 인증 미들웨어를 설정하는 방법도 고려해볼 수 있습니다.

운영환경에서 문서가 열려 있으면 보안상 큰 위험이 될 수 있으므로 항상 환경에 맞는 설정을 적용하세요.

카테고리 다른 글