백엔드
Flask, marshmallow, apispec으로 API 문서화 자동화하기
두줄요약
Flask API의 검증 스키마를 marshmallow로 정의하고 OpenAPI 문서 생성에 재사용했습니다.\napispec을 연동해 API 명세 작성과 공유를 자동화하는 방식을 소개합니다.
구조와 흐름
- Flask API의 요청·응답 스키마를 marshmallow로 선언하고 검증·직렬화에 활용
- 스키마 필드의 설명·예시 메타데이터를 OpenAPI 문서 생성 정보로 재사용
- apispec과 Flask 플러그인으로 OAS 3.0.2 문서 생성 및 시각화 도구 연계
선택 이유
- 프론트엔드·백엔드 분업 전환에 따른 API 명세 공유 필요성
- OpenAPI 표준 기반 문서화 도구·시각화 도구 활용 가능성
- 검증용 스키마와 문서용 스키마의 중복 작성 감소
주의할 점
schema.load검증 실패 시ValidationError를 400 응답으로 변환하는 예외 처리 필요- 백엔드 snake_case와 외부 API camelCase 차이를
CamelCaseSchema로 일관되게 변환
적용해볼 점
- 요청 파라미터, JSON 본문, 응답, 검증 오류 형식을 각각 스키마로 명시
- 인증 헤더·쿼리 파라미터·오류 응답까지 OAS 명세에 포함
