Swagger openapi 사용법

OpenAPI는 REST API를 사용하는데 필요한 정보를 담은 규격이다. yaml이나 json으로 endpoint, parameter, response 등 모든 api를 표현한다. OpenAPI 3.0.0부터는 Swagger specification이 OpenAPI specification으로 이름을 바꾸고 여러 다른 회사/단체와 힘을 합쳐 표준화가 진행되었다.

OpenAPI에서는 모델을 정의하고 재활용하는 문법을 통해 중복되는 선언을 줄일 수는 있지만 막상 작성하다 보면 크기가 방대해지는 건 어쩔 수 없다. 소스코드에서 api 명세를 작성하는 방법이나 다른 여러 방법들이 존재하지만 모든 불만을 충족시켜줄 순 없는 노릇이라 직접 해보며 경험을 쌓아보는 게 좋을 것 같다.

 

 

openapi

첫 줄은 openapi 버전으로 시작한다.

버전에 따라 변경되는 스펙이 있으니 참조하고 있는 문서의 버전을 확인하고 입력한다.

openapi: 3.0.2

 

info

api 정보를 입력한다. swagger로 구동 시 페이지 상단에 제목처럼 표시된다.
title, version 등 필수로 요구되는 설명을 작성하고 description,contact, licence 등 설명이 필요한 항목이 있으면 추가한다.

info:
  title: 서비스 api document
  version: 1.0.0

 

servers

명시한 api의 대상이 되는 서버를 배열로 나열한다. 개발/스테이징 환경의 endpoint를 추가하면 각 환경에서 손쉽게 REST API를 테스트할 수 있다.

servers:
  - url: http://dev-api.com
    description: dev endpoint

 

Components

여러 api에서 공통으로 사용되는 모델을 선언한다. 모델을 정의하는 schemas과 api request/response 들을 정의하는 parameters, responses등의 하위 옵션이 있다.
이렇게 선언한 components는 api 명세하는 곳에서 $ref로 참조해서 사용한다.

schemas

데이터 모델을 정의한다. 데이터 이름 다음에는 type 속성으로 해당 데이터의 타입을 명시한다.
자주 사용되는 타입의 종류는 array, string, boolean, number, object 등이 있다. 각 타입의 종류에 따라 필요한 속성들이 있다.

• array: items 속성을 추가해서 어떤 아이템들로 이루어지는지 명시해야 한다. 배열의 길이의 제한이나 unique 조건을 추가할 수 있다.
• string: 필수로 필요한 속성은 없고, regex pattern이나 글자 길이 제한을 추가할 수 있다. enum으로 사용하려면 enum 속성에 배열로 추가한다.
• object: properties 속성을 추가해서 어떤 key를 가지는지 명시한다.

이 문법을 바탕으로 schema를 작성하면 아래와 같다.

components:
  schemas:
    Grade:
      type: string
      enum:
        - A
        - B
        - C
    User:
      type: object
      properties:
        age:
          type: string
        email:
          type: string
        grade:
          $ref: '#/components/schemas/Grade'
    History:
      type: array
      items:
        type: string

parameters

parameters에는 api request에 사용되는 인자를 정의한다.

• in: path, query, header 중 필요한 값을 입력하고 schema로 해당 인자가 어떤 모델인지 나타낸다.
• name: request에서 in으로 가져올 파라미터의 이름을 사용한다.

components:
  parameters:
    pageableParam:
      name: page
      in: query
      schema:
        type: object
        properties:
          page:
            type: number
          size:
            type: number
    userId:
      name: user_id
      in: path
      schema:
        type: number

 

paths

클라이언트에게 제공되는 api를 나열한다. 먼저 api path와 method로 구분하고 해당 api에 필요한 parameter와 response를 작성한다.
여러 api에 공통으로 사용되는 모델과 parameter는 $ref를 사용해서 위 components에서 정의한 이름을 참조해서 사용한다.

• tags: 같은 모델 / 비슷한 역할을 하는 api를 묶어서 보여주는데 그 구분이 되는 key
• parameters: path, querystring, header, cookie를 지정하고 타입도 정의한다.
• requestBody: body에 데이터를 전달할 경우 해당 속성에 media type과 content를 추가한다.
• responses: 응답으로 status code와 함께 body가 있는 경우 requestBody와 마찬가지로 모델을 추가한다.

paths:
  /users/{user_id}:
    get:
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        200:
          description: User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

 

components.parameters에서 정의한 userId를 보면 in: path, name: user_id로 정의했기 때문에 $ref로 참조만 걸어도 해당 api에 잘 매핑된다.

response body에서 사용되는 모델도 compoents.schema에 정의한 User를 참조만 하면 그대로 사용할 수 있다.