🧾 Django REST Framework에서 API 문서 자동화하기 (DRF Spectacular + Swagger)

💡 왜 API 문서가 중요할까?

API는 개발자들이 사용하는 제품입니다.
좋은 API를 만든다고 해도, 사용법을 모르면 쓸 수 없겠죠?

“API는 문서화된 만큼만 가치가 있다.”

• 어떤 endpoint가 있는지
• 어떤 method(GET, POST 등)가 가능한지
• 어떤 데이터를 주고받는지
• 인증은 어떻게 하는지

이런 내용이 없다면, 그 API는 사용자가 없는 앱과 다를 바 없습니다.

---

🧪 TDD로 Django 프로젝트를 개발 중

이번 강의는 Django 심화 과정이었고, TDD(Test-Driven Development) 방식으로 API를 하나씩 만들고 있습니다.
예를 들어 POST /recipes/나 GET /tags/와 같은 API를 만들고 테스트로 검증하죠.

그런데 기능이 많아지면서, 내가 만든 API를 외부 개발자나 팀원들이 어떻게 사용할지 고민이 생겼습니다.
그래서 이번엔 API 문서를 자동으로 생성하는 방법을 배웠습니다.

---

📚 문서화 방식 두 가지

1. 수동 문서화 (추천 ❌)
   • Markdown 문서나 Word 문서로 작성
   • 기능 추가 시 수동으로 수정해야 함
   • 시간이 오래 걸리고, 최신 상태 유지가 어려움
2. 자동 문서화 (추천 ✅)
   • 코드에 작성한 정보로부터 문서를 자동 생성
   • API 변경사항이 문서에도 자동 반영
   • 테스트도 가능한 UI 제공

---

🧰 우리가 사용할 도구: DRF Spectacular + Swagger UI

• DRF Spectacular
  Django REST Framework용 문서 자동 생성 라이브러리
  → OpenAPI 3.0 스펙 지원 (업계 표준)
• Swagger UI
  OpenAPI 문서를 읽어서, 브라우저 기반의 인터페이스로 시각화
  → API를 직접 테스트하고 응답도 볼 수 있음

---

📄 Schema란?

DRF Spectacular은 내부적으로 schema를 생성합니다.
이 스키마는 .yaml 또는 .json 형식으로 작성되며, API의 모든 정보를 담고 있습니다.

예:

paths:
  /tags/:
    get:
      description: "List all tags"
      parameters:
        - name: "assigned_only"
          in: "query"
          required: false
          schema:
            type: "integer"
            enum: [0, 1]
      responses:
        "200":
          description: "Successful Response"

스키마는 Swagger와 같은 도구에서 자동으로 읽어서 사용자 인터페이스를 만들어줍니다.

---

🧑‍💻 Swagger UI로 문서화된 API 테스트하기

Swagger UI를 띄우면 다음과 같은 기능을 제공합니다:

• 모든 API 엔드포인트 목록 확인
• 각 요청의 method(GET/POST 등), 파라미터, 응답 예시 확인
• Try it out → 직접 API에 요청해보기
• 인증 토큰 입력 기능도 지원 (JWT, Token 등)

이렇게 문서와 테스트 도구가 하나의 페이지로 통합됩니다.

---

✅ TDD + 자동 문서화의 시너지

• TDD로 테스트 코드부터 작성하면, API 기능이 명확해지고
• docstring을 잘 작성하면, 문서도 자동으로 구성
• Swagger를 띄워서 바로 테스트 가능

테스트 + 문서 + 기능 구현
이 세 가지를 동시에 챙길 수 있다는 것이 이번 강의에서 가장 인상 깊었던 부분이었습니다.

---

📌 마무리하며

수동 문서화를 반복하는 대신, 코드를 기준으로 자동으로 문서를 생성하고,
그 문서 안에서 직접 API를 테스트할 수 있다면 얼마나 효율적일까요?

DRF Spectacular + Swagger UI 조합은 Django REST Framework에서 API 개발과 문서화를 정말 간편하게 만들어줍니다.

API를 팀과 공유하거나 오픈 API로 만들고 싶다면, 꼭 자동 문서화를 도입해보세요!

---

필요하다면 다음 글에서는 DRF Spectacular 설치 및 설정법도 단계별로 정리해드릴게요.
이 글이 도움이 되셨다면 공감 ♥️ 또는 댓글로 알려주세요!