좀 더 자세한 이야기는 다음 연결 글을 참고!
OpenAPI 명세, Swagger 기본 개념 : Django restframework, drf-spectacular로 swagger split
1. open api와 swagger, redoc의 개념
OpenAPI는 OpenAPI Specification (OAS)이라고도 불리는데, REST API의 스펙을 규칙에 맞게 json이나 yaml로 표현한 문서를 말한다. Django 에서는 일반적으로 프로젝트에 Schema.yml 이나 Schema.json 파일로 프로젝트의 API 구조를 뼈대처럼 작성해놓는다. 물론 자동으로...
예시) schema.yml 파일의 일부
Swagger나 redoc은 이런 Schema.yml 파일을 기반으로 각 API들의 입출력 구조를 보여준다. 특히 swagger는 테스트까지 해볼 수 있다.
2. drf-spectacular, drf-yasg
drf- 로 시작하는 상기 이름들은 Django에서 사용하는 OpenAPI 구성용 라이브러리를 뜻한다. 다만 drf-spectacular는 최신(2022.06 기준)의 OAS 3.0 스펙을 지원하는 버전이며 drf-yasg는 OAS 2.0을 지원하는 구버전의 라이브러리이다.
멀티 URL을 지원한다던가, request/response에 따라 구분하여 예시를 표현할 수 있는 기능들의 차이가 있고 재사용성이 좋도록 개선된 부분이 있으므로 왠만하면 OAS 3.0을 적용하는 것이 좋다.
3. Django에서 Swagger 설정: 간단한 원리 정도
다른 모든 복잡한 설정은 위에서 언급한 상세 내용 글 링크를 참조하는 것이 좋을 것 같다! 다만 가장 중요한 원리는 이 글에도 기록해둔다.
OpenAPI 명세, Swagger 기본 개념 : Django restframework, drf-spectacular로 swagger split
프로젝트 root 디렉토리에 Django 프로젝트에서 기본적으로 설정하는 urlpatterns 리스트 내부에 다음 2개의 path가 포함되어야 한다.
path('docs/json', SpectacularJSONAPIView.as_view(), name='schema-json'),path('docs/swagger/', SpectacularSwaggerView.as_view(url_name='schema-json'),
name='swagger-ui'),
완전히 정확하게 이해한 것은 아니지만... SpectacularJSONAPIView 객체에서 docs/json이라는 url 주소로 프로젝트의 schema를 json 파일로 만들어주고, {root-api}/docs/swagger/로 접속하면 이 docs/json에 생성된 schema를 기반으로 swagger가 보기좋게 swagger UI 페이지를 만들어준다.
-주의할 사항으로, drf-spectacular (OAS 3.0)은 BaseSerializer를 지원하지 않는다고 한다. 나는 임시적으로 BaseSerializer의 자식 클래스인 Serializer로 변경해주었다.
참조
1. 호롤리한 하루 - OpenAPI 란?(feat. Swagger)
https://gruuuuu.github.io/programming/openapi/
2. 정리 잘 된 문서
3. 깔끔한 참고 문서
https://velog.io/@catveloper/DRF-Spectacular-사용법
4. 공홈 settings 조건
https://drf-spectacular.readthedocs.io/en/latest/settings.html