[Node] node Express에 스웨거(Swagger) 추가하기

 

 

 

 

 

 

📌 node.js Express 서버에 스웨거 추가하는 방법

별도의 서버 구축 없이 Express 서버에 Swagger를 연결하는 방법에 대한 포스팅이다.

 

 

 

1️⃣ 스웨거 패키지 설치

npm install swagger-jsdoc swagger-ui-express --save-dev

◽ swagger-jsdoc : jsdoc 주석을 사용하여 Swagger API 문서를 작성하기 위한 패키지

◽ swagger-ui-express : swagger UI와 express를 연결하기 위한 패키지

 

 

 

 

2️⃣ 스웨거 설정파일 추가 및 route 등록

 

◾ 임의의 경로에 swagger.js 파일을 추가한다.

중요한 부분은 apis인데, 해당 부분에는 api 주석을 작성하는 경로를 입력해 준다.

보통 routes 경로를 입력하는데, 여기서는 깔끔함을 위해 컨트롤러 파일이 있는 경로를 입력하였다. 

/* swagger/swagger.js */
const swaggerUi = require("swagger-ui-express")
const swaggereJsdoc = require("swagger-jsdoc")
const options = {
  swaggerDefinition: {
  openapi: "3.0.0",
  info: {
      title: "Jinny`s Swagger",
      version: "1.0.0",
      description: "Node.js Swaager UI With.swagger-jsdoc"
  },
  servers: [
      {
        url: "http://localhost:3000/", // 요청 URL
      },
    ],
  },
  apis: ["./api/controllers/*.js"], //Swagger 주석이 존재하는 파일의 경로
}
const specs = swaggereJsdoc(options)

module.exports = { swaggerUi, specs }

 

 

◾ app.js 파일에 route를 등록한다.

nodejs의 최상위 컨테이너 파일인 app.js에 스웨거를 사용하기 위한 코드를 작성한다.

/* app.js */
const express = require("express")
const api = require("./routers")

const app = express()

// ...

const { swaggerUi, specs } = require("./swagger/swagger")
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs))

// ...

 

위 과정까지 마친 후 http://localhost:3000/api-docs 로 접속하면 아래와 같은 화면이 보인다.

 

 

 

 

 

3️⃣ api 문서화하기

swagger.js의 apis에 입력한 경로에 있는 파일로 돌아가 swagger 주석을 작성한다.

/* controllers/xxxController.js */
/**
 * @swagger
 * tags:
 *   name: Delivery
 *   description: Delivery API
 */
 
const deliveryController = () => {
  // 배송권역수신
  /**
   * @swagger
   * paths:
   *  /api/zipcodes:
   *    get:
   *      summary: "배송권역수신"
   *      description: "배송권역수신"
   *      tags: [getZipcodes]
   *      responses:
   *        "200":
   *          description: 배송권역수신
   *          content:
   *            application/json:
   *              schema:
   *                type: object
   *                properties:
   *                    ok:
   *                      type: boolean
   *                    users:
   *                      type: object
   *                      example:
   *                          [
   *                            { "key": 1, "value": "1" },
   *                            { "key": 2, "value": "2" },
   *                            { "key": 3, "value": "3" },
   *                          ]
   */
  const getZipcodes = async (req, res, next) => {
  	//...
  }

 

주석 작성 이후 다시 웹 화면으로 돌아가면 아래와 같이 보일 것이고, 이제 API 문서를 작성하면 된다.