25분

API 문서 - "이 엔드포인트 뭐 하는 거예요?" 방지법

Day 1: 기술 문서화 - 코드를 넘어 이야기를 남겨라

학습 목표

FastAPI 자동 문서화의 원리를 이해한다 Pydantic 모델로 API 문서 품질을 높이는 방법을 학습한다 OpenAPI/Swagger와 Postman Collection의 차이를 파악한다

"이 엔드포인트 뭐 하는 거예요?"

API를 만들었다. 5개 엔드포인트. 프론트엔드 개발자가 물어본다.

"/api/diagnose에 POST 보내면 되나요?" "body에 뭘 넣어야 하나요?" "응답 형식이 어떻게 되나요?"

매번 Slack으로 대답한다. 일주일 후, 같은 질문이 또 온다.

"아까 알려주셨는데 기억이 안 나서요..."

API 문서가 없으면, 개발자 = 살아있는 문서가 된다.

FastAPI가 해결해준다

FastAPI의 최대 장점: 코드 = 문서.

에디터 로딩 중...
에디터 로딩 중...

Pydantic 모델이 핵심이다

에디터 로딩 중...

Field 하나가 문서 품질을 결정한다

Field 속성역할효과
descriptionAPI 문서에 설명 표시개발자가 바로 이해
example테스트용 예시 자동 생성Try it out에서 바로 실행
ge, le값 범위 제한 + 문서 표시잘못된 요청 방지
default기본값 + 문서 표시Optional 필드 명확화

Swagger vs ReDoc vs Postman

도구장점단점추천
Swagger UI (/docs)바로 테스트 가능복잡한 API에서 느림개발 중 테스트
ReDoc (/redoc)가독성 최고테스트 불가공유용 문서
Postman팀 협업, 자동 테스트별도 설정 필요팀 개발

추천 조합: 개발 중 Swagger + 공유는 ReDoc + 팀 협업은 Postman

핵심 정리

  1. FastAPI의 코드 = 문서 철학을 최대한 활용
  2. Pydantic Field의 description, example이 문서 품질을 결정
  3. Enum으로 허용 값을 명시하면 문서가 더 명확
  4. /docs(테스트) + /redoc(공유) 조합이 최적
이전다음