백엔드 API 자동 문서화

백엔드 API 자동 문서화는 API를 정의한 코드 또는 명세를 기반으로 사용 가능한 API 목록, 매개변수, 응답 등을 자동으로 문서로 생성해주는 방식입니다. 아래에서 주요 도구들과 각각의 특징을 설명드릴게요.

---

✅ 대표적인 자동 문서화 도구

1. Swagger (OpenAPI) + Swagger UI

• 설명: 가장 널리 쓰이는 자동 문서화 도구. OpenAPI 명세를 기반으로 RESTful API 문서 생성.
• 사용법:
  • Flask: flasgger, apispec, flask-restx
  • Django: drf-yasg, drf-spectacular
  • FastAPI: 기본적으로 OpenAPI 스펙을 자동 지원
• 장점:
  • 인터랙티브한 UI 제공
  • 테스트 기능 포함
  • 다양한 언어/프레임워크 지원

2. Redoc

• 설명: OpenAPI를 기반으로 한 정적인 문서 생성 도구.
• 장점:
  • 깔끔하고 읽기 쉬운 UI
  • Swagger UI보다 가볍고 문서로서의 가독성이 뛰어남
  • GitHub Pages와 같은 정적 사이트에 배포 용이

3. FastAPI

• 설명: 자체적으로 Swagger UI와 Redoc을 내장하고 있어 자동 문서화가 기본 기능.
• 장점:
  • 타입 힌트를 기반으로 문서 자동 생성
  • 개발자가 별도 설정 없이 문서화 가능

4. Postman + API Documentation

• 설명: Postman에서 API를 관리하면서 문서화 가능
• 장점:
  • 협업 기능 탁월
  • API 테스트와 함께 관리 가능

---

📌 프레임워크별 예시

✅ Flask + Flasgger 예시

from flasgger import Swagger
from flask import Flask

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/api/hello')
def hello():
    """
    Hello endpoint
    ---
    responses:
      200:
        description: A successful response
    """
    return "Hello World"

✅ Django REST Framework + drf-yasg

# settings.py
INSTALLED_APPS += ['drf_yasg']

# urls.py
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="My API",
        default_version='v1',
    ),
    public=True,
)

urlpatterns += [
    path('swagger/', schema_view.with_ui('swagger')),
    path('redoc/', schema_view.with_ui('redoc')),
]

✅ FastAPI 기본 문서화

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

• /docs → Swagger UI
• /redoc → Redoc

---

🧩 기타 기능 및 팁

• 버전 관리: OpenAPI 3.x 스펙을 기준으로 작성
• JWT 인증 적용: securitySchemes을 설정해 문서 상에서도 인증 테스트 가능
• CI/CD 문서화 자동화: 문서 생성 후 정적 파일로 export해 GitHub Pages에 자동 배포 가능

---