Express 서버와 Swagger 연동하기

Swagger 설치

https://2mukee.tistory.com/790

swagger에 대해 알아보자

 

 

 

 

 

Express와 Swagger 연동

- 필요 패키지 설치

// 필요 라이브러리들을 개발 환경에 종속되게 설치
// swagger-jsdoc: jsdoc 주석으로 Swagger API 문서를 표현하기 위한 라이브러리
// swagger-ui-express: swagger-ui와 express를 연결하기 위한 라이브러리
npm install swagger-jsdoc swagger-ui-express -save-dev

 

-  Swagger 환경설정

: swagger/swagger.js 파일 생성

const swaggerUi = require("swagger-ui-express")
const swaggereJsdoc = require("swagger-jsdoc")

const options = {
  swaggerDefinition: {
    openapi: "3.0.0",
    info: {
      version: "1.0.0",
      title: "2mukee 연구소",
      description:
        "프로젝트 설명",
    },
    servers: [
      {
        // Express 서버 URL
        url: "http://localhost:3000",
      },
    ],
  },
  // Express Router와 Swagger 파일을 연결
  apis: ["./routers/*.js", "./routers/user/*.js"],
}
const specs = swaggereJsdoc(options)

module.exports = { swaggerUi, specs }

 

- Express server에 Swagger 적용

// ... exress server 관련 부분 생략

// swagger 모듈 불러오기
const { swaggerUi, specs } = require("./swagger/swagger")

// swagger로 테스트를 수행하는 API URL 정의
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs))

// ... express server 관련 부분 생략

: 브라우저로 localhost:3000/api-docs에 접속하면 swagger UI가 나옴

 

- API에 Swagger 적용

const router = require("express").Router()
const user = require("./user")

/**
 * @swagger
 * tags:
 *   name: Users
 *   description: 유저 추가 수정 삭제 조회
 */
router.use("/user", user)

module.exports = router

: 이후 localhost:3000/api-docs에 접속하면 해당 API에 대한 정보가 출력됨

 

- 문서화

const userRouter = require("express").Router()
const userController = require("./user.controller")

/**
 * @swagger
 * paths:
 *  /api/user/users:
 *    get:
 *      summary: "유저 데이터 전체조회"
 *      description: "서버에 데이터를 보내지 않고 Get방식으로 요청"
 *      tags: [Users]
 *      responses:
 *        "200":
 *          description: 전체 유저 정보
 *          content:
 *            application/json:
 *              schema:
 *                type: object
 *                properties:
 *                    ok:
 *                      type: boolean
 *                    users:
 *                      type: object
 *                      example:
 *                          [
 *                            { "id": 1, "name": "유저1" },
 *                            { "id": 2, "name": "유저2" },
 *                            { "id": 3, "name": "유저3" },
 *                          ]
 */
userRouter.get("/users", userController.getUsers)

module.exports = userRouter

: localhost:3000/api-docs에 접속하면 주석에 기입한대로 API의 스펙이 출력됨

 

 

 

 

 

 

 

Reference

[Swagger] Node.js Swagger API 문서화