안녕하세요. 글쓰는 개발자 입니다.
Frontend와 원활한 협업과 의사소통 비용 감소를 위해 API 문서화를 중요하게 생각합니다. drf_yasg 를 활용해서 Backend에서 쉽게 작성하고, API 문서를 보는 사람이 최대한 편하게 읽을 수 있도록 고민을 많이 했습니다. (참고: Django Swagger 연동하기 1편, 2편)
그러던 어느 날(약 1년 전) FastAPI 를 처음 접하게 되었고 Pydantic을 활용해 endpoint의 argument에 type만 지정해주면 자동으로 문서가 작성되는 것을 보고 신세계라 느껴졌습니다. 편리하다 생각했던 @swagger_auto_schema 데코레이터는 FastAPI를 접하고 '불편한', '한 번 더 작업해야하는' 것이라는 기분이 들었습니다.
그렇게 당시 바빴던 프로젝트 속에서 잊혀졌다가 최근 호기심에 Django에서 Pydantic에 대응하는 Serializer 를 활용해서 view의 request에 type으로 Serializer만 지정해주면 자동을 swagger가 그려지는 방법을 찾아보았고 아래와 같이 성공했습니다.
drf_yasg 의 동작이 궁금하신 분들은 재미로 봐주시면 감사하겠습니다.
저는 고민을 하던 중 일단 평소에 사용하던 @swagger_auto_schema 데코레이터가 어떻게 인자로 받아 온 Serializer에 정의된 값들을 문서로 변환 할 수 있게 하는지 아래와 같은 접근법으로 찾아냈습니다.
- @swagger_auto_schema 동작 분석
- Debugger 활용, @swagger_auto_schema 인자 값 처리 부분 확인
- request에 정의된 Type 가져오는 위치 확인
- 해당 위치에서 @swagger_auto_schema 를 사용할 때와 동일한 결과값을 생성하여 주입
그 결과 django에서 swagger 를 사용하기 위해 설치했던 drf_yasg 패키지 내부의 generator.py 의 get_overrides 메소드를 아래와 같이 if not overrieds 블록을 추가하는 방법으로 성공했습니다.
코드를 찬찬히 살펴보면, getattr을 활용해 _swagger_auto_schema 인자가 있는 지 먼저 확인합니다. 아래 이미지와 같이 swagger_auto_schema의 일부를 보면, view_method._swagger_auto_schema 에 data를 추가하는 것을 알 수 있는데, @swagger_auto_schema 사용 여부를 getattr로 검증 합니다.
하지만 저는 번거롭게 decorator를 쓰지 않을 것이기 때문에 overrides는 {} 이 됩니다. 그리하여 저는 if문 내부에서 직접 Schema를 정의했습니다. 여기서 inspect 내장 모듈을 활용해 action_method에 Type으로 선언한 Serializer를 불러올 수 있었습니다.
결론
하지만, 이것을 실무에서 사용하는 데에 무리가 있다고 판단했습니다. 라이브러리를 직접 수정하여 사용하는 것이 배포 환경에 패키지 설치가 번거롭다는 점과 라이브러리 업데이트 시 대응하기 힘들다는 점 때문에 사내 백엔드 개발자들에게 10분 내외로 세미나만 가지고 재밌는 경험(?) 정도로 넘어갔습니다.
조금씩 시간을 내서 query string, request body 모두 커버 가능한 모듈을 만들어서 오픈소스 기여자가 되어보고싶기도 합니다.