Swagger를 활용한 API-Docs 만들기

Swagger는 REST API를 쉽게 문서화하고 테스트할 수 있도록 도와주는 도구다.

먼저 03-03-rest-api-with-express-board 폴더를 복사 붙여넣기 한 다음,
폴더명을 03-04-rest-api-with-express-swagger로 변경해 줍니다.

Node.js로 구현한 API를 swagger와 연결하기 위해 설치해야 할 npm 모듈이 2가지 있다.

1. swagger-ui-express

   https://www.npmjs.com/package/swagger-ui-express?activeTab=readme

2. swagger-jsdoc

   https://www.npmjs.com/package/swagger-jsdoc

• API 설명이 적힌 파일을 넘겨주면, express에서 위의 이미지와 같은 사이트를 만들어준다.
• 주석으로 API에 대한 설명을 적으면 swagger-ui-express에 넘겨주기 위한 문서를 만든다.

터미널에서 03-04-rest-api-with-express-swagger 로 이동한 이후,

아래의 명령어를 입력해 swagger-ui-express와 swagger-jsdoc을 설치한다.

yarn add swagger-ui-express swagger-jsdoc

swagger-ui-express npm 사이트를 참고하여 swagger UI를 만들어보자.

Express setup app.js 항목에 있는 내용을 사용하는 방식에 맞게 고쳐준다.

그 다음으로는 swaggerUi를 import 해야한다.

마찬가지로 swaggerDocument도 import 해주자

// index.js

import swaggerUi from 'swagger-ui-express'
import swaggerJSDoc from 'swagger-jsdoc'

// ...생략

다음으로는 API 문서를 만들어주는 설정이 필요하다.

이번에는 swagger-jsdoc npm 사이트를 참고해보자.

위 코드는 swagger를 구현하기 위한 설정 코드다. 이를 참고하여 코드를 작성해보자.

먼저 swagger 문서와 관련된 파일을 따로 관리하기 위해 03-04-rest-api-with-express-swagger 폴더에 swagger 라는 폴더를 새로 만들어준다.

만들어준 swagger 폴더에 config.js 파일을 만들어 위에서 설명한 설정 부분을 분리해 작성하자

config.js에 아래의 내용을 작성한다. 정보들을 작성해주고, apis에는 swagger 파일들을 잘 읽어올 수 있도록 경로 설정을 바르게 해준다.

// config.js - swagger 의 설정파일 

export const options = { 
    definition: {
      openapi: '3.0.0',
      info: {
        title: '나만의 미니프로젝트 API 명세서!!',
        version: '1.0.0',
      },
    },
    apis: ['./swagger/*.swagger.js'], // swagger.js 로 끝나는 파일을 모두 api-docs 로 인식한다. 
  };

마지막으로 해야할 작업이 남아있다. 다시 한번 swagger-jsdoc npm 사이트를 참고해보면

swagger-ui-express의 npm 문서를 조금 내려보면 위와 같은 내용이 있다.

저기 존재하는 swaggerJSDoc(options) 코드의 options는 위에서 작성한 config.js 파일 내의 내용이다. index.js 파일에서 import 해줘야 한다.

결과적으로 해당하는 내용들이 모두 수정된 아래의 코드를 index.js 파일에 추가해 줘야한다.

// index.js

import swaggerUi from 'swagger-ui-express'
import swaggerJSDoc from 'swagger-jsdoc'
import { options } from './swagger/config.js'

// ...생략

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerJSDoc(options)));

// ...생략

swagger-jsdoc npm을 참고하여 board api와 관련된 설명을 형식에 맞게 작성해보자.

swagger 폴더 안에 boards.swagger.js 파일을 만들고, 아래 내용을 넣어주자.

swagger 문서는 들여쓰기에 유의해서 적어주어야 한다.

// boards.swagger.js

/**
 * @swagger
 * /boards:
 *   get:
 *     summary: 게시글 가져오기
 *     tags: [Board]
 *     parameters:
 *       - in: query
 *         name: number
 *         type: int
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 properties:
 *                   number:
 *                     type: int
 *                     example: 1
 *                   writer:
 *                     type: string
 *                     example: 철수
 *                   title:
 *                     type: string
 *                     example: 좋은아침 입니다~
 *                   contents:
 *                     type: string
 *                     example: 오늘 하루도 파이팅 하세요!
 */


/**
 * @swagger
 * /boards:
 *   post:
 *     summary: 게시글 등록하기
 *     tags: [Board]
 *     responses:
 *       200:
 *         description: 성공
 */

❓ 어떤 내용을 작성해야하는지 아래의 공식문서를 참고해 공부할 수 있다.

https://swagger.io/docs/specification/basic-structure/

이제 터미널에서 해당 폴더로 이동한 후, node index.js 로 서버를 띄워준다.

http://localhost:3000/api-docs/ 를 접속해보면, 아래와 같은 내용을 확인할 수 있다.