TIL 20210616 swagger(flasgger)에서 OpenAPI 3.0 사용 시 spec 작성법

https://github.com/flasgger/flasgger/

API 문서화용으로 swagger(flasgger)를 사용하고 있는데, OpenAPI 3.0을 적용한 이후로 POST, PUT메소드 등, request body가 필요한 API에서 request body를 입력해도 인식하지 못하는 상황이 발생.

원인을 찾아본 결과 OpenAPI 3.0부터 specification(이하 spec)을 작성하는 방법이 약간 달라졌기 때문이었다.
기존 버전에서는 request body가 있을 경우 다음과 같은 방법으로 작성해야 했다.

def post(self):
"""
   This is an example
   ---
   tags:
     - restful
   parameters:
    - in: body
       name: body
       schema:
         $ref: '#/definitions/Task'
   responses:
     201:
       description: The task has been created
       schema:
     	 $ref: '#/definitions/Task'
"""
  ...
  return 

parameters 부분을 주목.

OpenAPI 3.0에서는 request body가 별도의 requestBody 항목으로 분리되었다.

def post(self):
  """
  tags:
  - pet
  summary: Updates a pet in the store with form data
  operationId: updatePetWithForm
  parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      type: string
  requestBody:
    content:
      'application/x-www-form-urlencoded':
        schema:
         properties:
            name: 
              description: Updated name of the pet
              type: string
            status:
              description: Updated status of the pet
              type: string
         required:
           - status
  responses:
    '200':
      description: Pet updated.
      content: 
        'application/json': {}
        'application/xml': {}
    '405':
      description: Method Not Allowed
      content: 
        'application/json': {}
        'application/xml': {}
  security:
  - petstore_auth:
    - write:pets
    - read:pets
  """
  ...
  return 

예시 참고한 출처: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#operation-object-example