[TIL] API 자동화 문서 말 그대로 멋진 SWAGGER 11/04 05일차 [1/2]

- Today I Learned

-  이전에 보았던 POST맨에서는 각 API를 직접 추가하고 수정하고 작성해야했다.

 

    API를 만들게되면 프론트엔드 개발자와 소통하면서

    API가 추가되었고,request,url,method,response_body,request_query_params 등

    공유 해주어야 프론트엔드 개발자는 이를통해 API를 연동하고 실제 서버에서 데이터를 불러 올 수 있는데

    이 과정에서 수기나 말로 전달하기에는 번거롭고 아무래도 소통간의 오류가 있을수 있기 때문에

     API를 자동으로 문서화 시켜주고 수정할때마다 자동으로 업데이트되어 프론트엔드 혹은 다른개발자들이

     API 명세를 바로 확인할 수 있고 뿐아니라 목업(Mock-up) 테스트도 지원하기 때문에 

    연동이 되어있지 않더라도 Response를 확인해볼 수 있는 강점이 있다.

 

더이상 싸우지말자

 

    Swagger을 통해 정확한 협업과 소통이 가능!

 

 

 

-  스웨거(SWAGGER)란?

 

장점

• 스웨거(Swagger)는 개발자가 REST API 서비스 설계, 빌드, 문서화할 수 있도록 하는 프로젝트이다.
• API에 대한명세(Spec)을 관리하기 위한 프로젝트이다.
• API가 수정되더라도문서가 자동으로 갱신된다

 

단점

• 변경 이력관리가 안됨
• 코드 침투적[어노테이션(주석) 도배]

                        - 어노테이션은 코드 사이에 주석처럼 쓰여서 특별한 의미, 기능을 수행하도록 하는 기술이다.

 

- 스웨거 사용방법은 크게 2가지가 있다.

• Swagger Hub라는 Swagger를 만들 곳의 Cloud를 이용하여 직접 관리하는 방법(구글검색)
• 각자 회사에 직접 Swagger 모듈을 도입하여 적용하는 방법(아래참조)

 

 

- Swagger 모듈 라이브러리 설치

Django에서 지원하는 여러가지 Swagger 모듈 중 대표적인 drf-yasg가 있다고 한다.

drf-yasg는 장고로 정의된 API를 문서화하는 패키지로.

(django rest framework- Yet another Swagger generator)의 약자이다.

 

drf-yasg는 drf 환경 위에서 동작하도록 되어있기 때문에 설치전 DRF를 설치해야한다.

 

pip install drf-yasg
pip install djangorestframework

 

- 모듈 설치한후 Django에 setting.py에 추가해준다.

Setting.py

 

- 스웨거를 보기위해 관련 코드를 urls.py 에 추가해준다.

 

밑에 drf-yasg홈페이지 내에 urls.py 안내문

https://drf-yasg.readthedocs.io/en/stable/readme.html

drf-yasg - Yet another Swagger generator — drf-yasg 1.20.1 documentation

 

함수가 url 밑으로 가면 url에서 함수를 읽지못한다.

 코드는 위에서아래로 탑다운(하향식)으로 읽어오기 때문에

 url에서 함수를 읽어야하는데 url보다 밑에있으면 인식하지 못하기 때문

sattings.py의 urls.py

정상적인 작성방법

작성 후 저장! 하고 런서버를 하면

Swagger 적용된 화면

url에 로컬서버/swagger를 입력해준다.

 

Article의 게시글 조회 화면

 

 

-------------------------------------------------------------------------------------------------------------------

Swagger의 부가기능

view파일 모듈

view파일 / drf_sasg.utils 에서 스키마 추가전 import 해준다.

 

스키마 정의:컴퓨터 과학에서 데이터베이스 스키마(database schema)는

                    데이터베이스에서 자료의 구조, 자료의 표현 방법, 자료 간의 관계를 형식 언어로 정의한 구조

 

 

POST의 body

GET의 Query String

Header를 설정하는 방법

해당 기능은 라이브러리에서 제공하는 데코레이터에 시리얼라이저만 넘겨주면 구현된다.

 

API는 request를 받을 때 데이터를 요구한다.drf-yasg는 API 요청 시에 필요한 데이터를

Swagger 문서에서 보여주고, 사용하게 해주는 기능을 제공한다.

 

- POST의 body 추가 기능

포스트 함수위에 데코레이터를 추가

 POST를 담당하는 메소드에 @swagger_auto_schema 데코레이터를 추가한다.
 이 데코레이터는 파라미터로 request_body를 받는데,

해당 파라미터 값으로는 시리얼라이저 타입(ArticlesSerializer)만 와야 한다.

POST에 BODY가 추가된 모습.

스웨거를 이용한 POST 작성

POST후의 Response

잘 저장된모습.

 

Request에 포함시키지 않고 싶은 필드가 있는경우 :

Serializer를 커스텀하고 스키마 데코레이터 바디에 반영해주면 된다.

아무 바디를 주고 싶지않은 경우 위의 사진과 같이 no_body를 import 해주고 데코레이터 바디에 그대로 반영한다.

POST에서 Request가 사라진 모습

 

- GET의 Query String

스키마 인자에 지정된 값을 넣어준다.

GET을 담당하는 메소드에 @swagger_auto_schema(query_serializer=Serializer명)

POST와 동일하게 시리얼라이저 객체를 받는다.

발췌 : https://velog.io/@lu_at_log/drf-yasg-and-swagger

발췌 : https://velog.io/@lu_at_log/drf-yasg-and-swagger

- Header 추가하기

발췌 : https://velog.io/@lu_at_log/drf-yasg-and-swagger

https://velog.io/@lu_at_log/drf-yasg-and-swagger

 

 

 

 

 

이처럼 작성한 API를 따로 POST맨에서 작성하지 않아도

Swagger모듈에서 API를 자동으로 문서화 시켜주고 갱신해주며 각각의 API를 테스트를 해볼수 있다.

 

회고 : DRF를 배우고 있어 SWAGGER에 대해 간단하게 확인만 해보았다.

          GET의 Query String,Header의 대한 내용도 실습하고 타이핑하고 싶었지만

          CBV의 ViewSet의 대한 내용이 있어서 시간도 부족하고

          API가 익숙해지면 다뤄보는걸로하고 일단 발췌를 해두었다.

 

          포스트맨,SWAGGER 외 여러가지 모듈이나 프로그램들이 있지만

          퓨어장고,DRF 등 하나씩 알아갈수록 점점 짧아지지만 내용이 어려워진다

          각각의 만든사람들의 의도를 이해하고 사용방법을 이해한다면 

          편리하게 이용할 수 있을 것 같다.

          물론 무엇이 편리하든 아니든 각각의 장단점이 있겠지만

          SWAGGER가 없었을땐 프론트엔드와 백엔드는 어떤 환경에서 일했을까..?

     

         이 같은 좋은 프로그램은 점점 더 나오겠지 하나씩 / 갑자기 떠오른 격언

      바퀴를 다시 발명하지 마라 - Don't reinvent the wheel

이미지출처 : 이미지1 , 이미지2

참조 및 발췌 : drf-yasg를 이용한 Swagger 문서 자동화 lu_at_log님 벨로그

자료출처 : [Django]Swagger를 통한 API 문서 작성하기

링크 : DRF-YASG