Swagger 설정하기

Swagger(스웨거)

API 문서를 자동으로 생성해주는 오픈소스 프레임워크이다.

Node.js 에서는 swagger-autogen 모듈을 사용할 수 있다.

swagger-autogen 모듈은 Swagger .json 파일을 생성한다.

해당 파일을 해석하기 위해서 swagger-ui-express 모듈과 express.js 모듈을 사용하여 서버를 생성하고, 일부 포트에서 문서를 사용할 수 있도록 한다.

NodsJS + Typescript + express

모듈 설치

npm i swagger-cli swagger-ui-express yamljs
npm i -D @types/swagger-ui-express @types/yamljs

swagger-cli : yaml 파일을 합치는 데에 사용된다.

swagger-ui-express : 작성한 API 명세를 UI로 보여준다.

yamljs : TS 파일로 yaml 파일을 읽어온다. → js-yaml 과 달리 any 타입을 반환한다.

openapi 설정 및 UI 의 URL 지정

openapi.yaml

openapi: '1.0.0'
info:
	version: 1.0.0
	title: API docs
	description: API 문서
	license:
		name: MIT
servers:
	- url: [address] //ex)localhost:3000
paths:
  $ref: './path.yaml'
components:
  parameters: null
  schemas:
    User:
      type: object
      required:
        - _id
        - name
      properties:
        _id:
          type: number
          description: id
        name:
          type: string
          description: 유저 이름
    Error:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
  responses:
    BadRequest:
      description: 잘못된 요청
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: 잘못된 요청
    InternalServerError:
      description: 서버 에러
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: 서버 내부 오류

path.yaml

/user:
  get:
    summary: Returns user list
    responses:
      '400':
        $ref: './openapi.yaml#/components/responses/BadRequest'

index.ts

import express from 'express'
import path from 'path';
import swaggerUI from 'swagger-ui-express'
import YAML from 'yamljs'

function makeServer(){
    const app = express();
    const port = 4242;

    const swaggerSpec = YAML.load(path.join(__dirname, './swagger.yaml'));
    app.use('/docs', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
    app.listen(port, ()=>console.log(`Listening on port ${port}`));
}
makeServer();

/docs 경로에 swagger UI를 연결한다.

package.json

"scripts": {
    "doc": "swagger-cli bundle ./openapi.yaml --outfile ./swagger.yaml --type yaml"
  },

bundle: openapi.yaml 파일 내에서 $ref 로 참조한 yaml 파일들을 합치기위한 명령어이다.

—outfile [file] : bundled API 가 출력으로 저장된다.

—type [type] : default는 JSON 파일로 저장된다. yaml 타입으로 저장되도록 설정한다.

yaml 파일 업데이트

npm run doc

server 실행하기

npm index.ts

[경로]/doc : 경로를 이동하여 swagger가 제대로 출력되는 지 확인할 수 있다.