[ NodeJS ] express에서 swagger로 API 명세서 만들기

[ NodeJS ] express에서 swagger로 API 명세서 만들기

포스트맨으로 API 명세서로 활용하고 있었는데 API 서버 정보가 포스트맨 서버에 저장되는 문제가 우려돼 swagger로 자체 API 서버에 연결을 해서 해결을 해보려고 한다.

npm i swagger-jsdoc swagger-ui-express —save -dev

swagger-jsdoc: jsdoc 주석으로 api 문서를 표현하는 용도
swagger-ui-express: swagger와 express 연결하는 용도

project/swagger/swagger.js

const swaggerUi = require("swagger-ui-express")
const swaggereJsdoc = require("swagger-jsdoc")
const CONFIG = require('../config/config');

const options = {
    swaggerDefinition: {
        openapi: "3.0.0",
        info: {
            version: "1.0.0",
            title: “project-backend",
            description:
                "프로젝트 설명 Node.js Swaager swagger-jsdoc 방식 RestFul API 클라이언트 UI",
        },
        servers: [
            {
                url: `http://localhost:${CONFIG.port}` || 'http://localhost:3000', // 요청 URL
            },
        ],
    },
    apis: ["./routes/*.js", "./controllers/*.js"], // Swagger 파일 연동
}
const specs = swaggereJsdoc(options)

module.exports = { swaggerUi, specs }

project/app.js

const { ReE } = require('./services/util.service');
app.use(cors());
app.use('/v1', v1);

const { swaggerUi, specs } = require("./swagger/swagger")
const swaggerJsdoc  = require('swagger-jsdoc')


app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs, {explorer: true}))

이제 /api-docs 경로를 들어가보면

 

정상적인 웹페이지를 확인할 수 있다.

이제 API 문서화를 진행해보자.

project/routes/v1.js

/** comment.controller **/
/**
 *  @swagger
 *  tags:
 *    name: Comments
 *
 */
// comment 등록
router.post('/comments', winstonLogger.loggingHeader, CommentController.addComment);
/**
 * @swagger
 * paths:
 *  /v1/comments:
 *    post:
 *      summary: "comment 등록"
 *      description: "유저가 작성한 comment 등록"
 *      tags: [Comments]
 *      responses:
 *        "201":
 *          description: 등록된 comment 정보
 *          content:
 *            application/json:
 *              schema:
 *                type: object
 *                properties:
 *                    message:
 *                      type: string
 *                      example: "Add comment success"
 *                    data:
 *                      type: object
 *                      example:
 *                          {
 *                            "msg": "hi",
 *                            "like": 777,
 *                            "type": "normal",
 *                            "_id": "63e0d4225d4fe1d514d52be6",
 *                            "createdAt": "2023-02-06T10:19:14.275Z",
 *                            "updatedAt": "2023-02-06T10:19:14.275Z",
 *                          }
 *                    success:
 *                      type: boolean
 *                      example: true
 *
 *
 */

정상적으로 API들이 뜨는 것을 확인할 수 있다.

** 유의할 점은 주석을 작성할 시 tab을 누르면 사용자의 작업환경에 따라 tab의 길이가 다르기 때문에 오류가 발생할 수 있다.

-> 그래서 스페이스바로 간격을 잘 확인한 뒤 작성하길 추천한다.