Flask, marshmallow, apispec으로 API 문서화 자동화하기

간단 소개

Flask, Marshmallow, Apispec을 활용한 API 문서 자동화 방법과 플러그인 개발 사례를 소개합니다.

AI Summary

API 문서 자동화의 필요성
- 과거 스포카는 풀 스택 개발 문화로 API 문서가 부족했지만, 프론트엔드/백엔드 분리 후 API 문서의 중요성이 커짐
- **OpenAPI Specification(OAS)**을 활용하여 효율적인 API 문서 작성 및 공유를 목표
Flask, Marshmallow, Apispec 활용
- Marshmallow: 파이썬 객체의 직렬화/역직렬화 및 검증을 위한 유틸리티, 스키마 정의를 통해 OAS 문서 자동 생성 용이
- Apispec: OAS 명세 작성 도구, 플러그인을 통해 Flask 등 다양한 웹 프레임워크 지원
- 예제 웹 서버를 구축하여 API 문서 자동화 과정을 설명하고, CamelCase 스키마 적용 및 ValidationError 처리 방법을 제시
플러그인 개발 및 적용
- AccessTokenPlugin: 액세스 토큰이 필요한 API에 자동으로 관련 문서 추가
- ValidationErrorPlugin: 요청 검증 실패 시 발생하는 400 에러를 문서화
- BasicInfoPlugin: API 엔드포인트 정보를 활용하여 operationId, summary, tags 자동 생성
- NoDocumentErrorPlugin: 문서가 없는 API 엔드포인트 방지 (테스트 환경에서 활성화)
- ValidateOnDumpSchema: 테스트 도중 응답 데이터가 스키마와 일치하는지 검증