지난 글에 기본 세팅까지 마쳤고 이제 실제적으로 API 작성에 따른 drf-yasg에 어떻게 적용하는지 알아보자
API생성
- GET METHOD
이 경우에는 swagger 상에서 쿼리 스트링을 설정하여 테스트 할 수 있다.
아래 예제 코드는 ListModelMixin Viewset으로 만든 간단한 get method api이다.
@swagger_auto_schema 데코레이터를 통해 각 엔드포인트의 메서드에 붙여주면 된다. 추가적으로 설정한 것들은
- operation_summary가 스웨거 ui상 제목이 되고
- opeartion_description이 설명란
- tags는 스웨거 ui상 API를 분류하는 카테고리의 일종이고
- manual_parameters — 이 부분이 가장 중요한 부분으로 get method에서 프론트단에서 검색조건이 설정되는 경우 혹은 변수에 의해 로직이 구성될 때 파라미터를 보내는 코드로 query_string의 형태로 url를 호출하도록 하는 기능이다.
추가적으로 response는 API상의 response를 그대로 표현하지만 커스텀하려면 swagger_auto_schema에 따로 설정해야 한다. GET의 경우 보통 list 표현인 경우가 많으므로 response도 Serializer의 형태를 그대로 따라가게 된다.
이렇게 설정하면 아래의 화면으로 나타난다.
2. POST/PUT/PATCH/DELETE METHOD
이 경우에는 swagger 상에서 body- payload를 설정하여 테스트 할 수 있다.
아래 예제코드는 CreateModelMixin Viewset을 통해 구현한 간단한 post 엔드포인트다.
GET 메소드 방법과 크게 다르지 않다. 다만 swagger_auto_schema의 설정 부분이 바뀌었다.
- request_body — post 메소드로 body payload를 보내는 부분으로 post 메소드에서 가장 중요한 부분이다. 따로 payload를 보낼 필요가 없는 api일 경우 request_body = no_body로 선언하면 payload가 ui상에서 나타나지 않는다.
POST의 경우 API가 list를 표현하지 않고 CRD의 행태를 취한다면 response도 message 형태로 띄우는 경우가 많다. 이럴 경우 공통으로 api단에서 response 클래스를 만들어서 그대로 사용하지만 이 API에서만 따로 사용해야 한다면 swagger_auto_schem에 response를 따로 설정해야한다.
설정하면 아래의 화면으로 나타난다.
swagger_auto_schema 데코레이터 설정 params
- method — 해당 메소드에서 매핑되는 http method가 하나만 존재할 때
- methods — 해당 메소드에서 매핑되는 http method가 둘이상 존재할때
ex) 함수형 view에서 api_view 데코레이터에서 as_view()가 여러개 존재하는 경우 - auto_schema — default는 drf-yasg 패키지상의DEFAULT_AUTO_SCHEMA_CLASS를 사용한다.
- request_body — request의 body payload이다. json형태의 값
- query_serializer — 쿼리 구문 분석을 위해 serializer 사용하는 경우
- operation_id — 유니크한 작업_id
- operation_description — 제목과 Parameters 사이에 설명
- operation_summary — API 제목
- security -특별한 인증방법을 쓰는 경우 설정
- deprecated — API중단여부
- responses — default는 API상의 response와 바라보는 models의 serializer를 따라감, 스웨거 상에서 커스텀한 response가 있을 시 설정
- field_inspectors — default : drf_yasg.inspectors.FieldInspector
- filter_inspectors — default : drf_yasg.inspectors.FilterInspector
- paginator_inspectors — default : drf_yasg.inspectors.PaginatorInspector
- tags — 스웨거 ui상의 API 카테고리
- **extra_overrides
manual_parameters
from drf_yasg.openapi import ParameterParameter를 상속 받아서 작성하는 부분으로 GET Method에서 query_string으로 검색조건을 보내기 위해 자주 이용된다.
Parameter("title", IN_QUERY, type=TYPE_STRING, description="제목"),- param str name: parameter name
- param str in_: parameter location
- param str description: parameter description
- param bool required: whether the parameter is required for the operation
- param schema: required if `in_` is ``body``
- type schema: Schema or SchemaRef
TYPE_OBJECT = "object" #:
TYPE_STRING = "string" #:
TYPE_NUMBER = "number" #:
TYPE_INTEGER = "integer" #:
TYPE_BOOLEAN = "boolean" #:
TYPE_ARRAY = "array" #:
TYPE_FILE = "file" #:- param str type: parameter type; required if `in_` is not ``body``; must not be ``object``
- param str format: value format
# officially supported by Swagger 2.0 spec
FORMAT_DATE = "date" #:
FORMAT_DATETIME = "date-time" #:
FORMAT_PASSWORD = "password" #:
FORMAT_BINARY = "binary" #:
FORMAT_BASE64 = "bytes" #:
FORMAT_FLOAT = "float" #:
FORMAT_DOUBLE = "double" #:
FORMAT_INT32 = "int32" #:
FORMAT_INT64 = "int64" #:# defined in JSON-schema
FORMAT_EMAIL = "email" #:
FORMAT_IPV4 = "ipv4" #:
FORMAT_IPV6 = "ipv6" #:
FORMAT_URI = "uri" #:# pulled out of my ass
FORMAT_UUID = "uuid" #:
FORMAT_SLUG = "slug" #:
FORMAT_DECIMAL = "decimal"
- param list enum: restrict possible values
- param str pattern: pattern if type is ``string``
- param .Items items: only valid if `type` is ``array``
- param default: default value if the parameter is not provided; must conform to parameter type
