[Swagger] Node.js에 Swagger 적용하기 (2) - OpenApI

openapi.yaml 파일 뜯어보기

openapi.yaml

앞서 [Swagger] Node.js에 Swagger 적용하기(1) 에서 기본 설정을 해주는 openapi.yaml 파일을 자세하게 보려고 한다!

자세한 공식 문서는 이 링크에

 

openapi

OpenAPI 사양의 버전을 명시해준다. 현재 코드에서는 OpenAPI 3.0.0을 사용한다.

openapi: 3.0.0

 

info

API 정보가 들어있다.

version : API의 버전

title : API 이름

description : API에 대한 설명(확장 정보)

license : API의 라이센스 정보

info:
  version: 1.0.0
  title: Wooly API Docs
  description: Wooly API 문서입니다
  license:
    name: MIT

 

Servers

API 서버 및 기본 URL을 지정한다. 여러 서버를 정의할 수 있다.

servers:
  - description: dev server
    url: http://localhost:3232

 

Paths

API 경로를 명시해준다. API의 각 경로와 이런 경로에서 지원하는 HTTP 메서드를 정의한다.

현재 코드에서는 경로를 여러 yaml 파일로 나눠 사용하기 위해 파일을 참조하여 정의했다.

paths:
  $ref: "./paths/_index.yaml"

해당 경로의 _index.yaml 파일은 아래와 같이 되어있다.

/app/promise-list:
  $ref: "./promise-list.yaml"
/app/promise:
  $ref: "./promise.yaml"
/sign-up:
  $ref: "./signup.yaml"
/sign-in:
  $ref: "./signin.yaml"

각 경로를 각각의 yaml 파일로 다시 분리해주었다. 이렇게 사용할 경우, 서버 통신 코드에서 Swagger 코드를 작성하지 않아도 되기 때문에 파일이 각각 하는 일이 명확해진다.

 

위의 경로 /app/promise-list의 yaml 파일을 보면,

promise-list.yaml

HTTP 메서드와, 해당 API에 대한 설명, 응답 등이 들어있다. 더 많은 정보는 Paths and Operations에

 

Components

Components의 schemas에는 재사용이 가능한 다양한 스키마들을 정의한다.

components:
  schemas:
    Promise:
      type: object
      required:
        - promiseIdx
        - promise
        - createdAt
        - public
        - userIdx
      properties:
        promiseIdx:
          type: integer
          description: ObjectID
        promise:
          type: string
        createdAt:
          type: string
        public:
          type: string
        userIdx:
          type: integer
    Auth:
      type: object
      required:
        - token
        - userIdx
      properties:
        token:
          type: string
          description: 토큰
        userIdx:
          type: integer
          description: 유저 인덱스  
    Error:
      type: object
      properties:
        isSuccess:
          type: boolean
        code:
          type: integer
        message:
          type: string

Promise, Auth, Error 스키마를 정의했고, 이 스키마들은 다른 곳에서 $ref를 사용하여 참조할 수 있다.

 

 

 

현재 진행 중인 프로젝트에서는 여러 개의 yaml 파일을 분리하여 사용하고 있는데, 다음 포스팅에서는 분리하지 않고 사용하는 방법과의 차이점을 알아보려고 한다!