swagger-autogen 사용하기 [Node.js]

Swagger란?

개발한 Rest API를 편리하게 문서화 해주고 프론트 와의 협업에서도 쉽게 API를 호출하고 테스트 할수 있게 해줍니다.

즉, UI를 이용하여 API를 쉽게 테스트하여 개발자가 문서를 작성하지 않아도 되므로 개발 시간을 단축할수있고

API 버전 관리가 용이해지고 다양한 API문서를 통합할 수 있습니다.

 

패키지 설치

// yarn 패키지
yarn add swagger-ui-express
yarn add swagger-autogen

// npm 패키지
npm install swagger-ui-express
npm install swagger-autogen

 

모듈 설정 및 경로 설정하기

//app.js
import swaggerUi from "swagger-ui-express";
import swaggerFile from "./swagger-output.json" assert { type: "json" };

app.use("/swagger", swaggerUi.serve, swaggerUi.setup(swaggerFile));

 

루트 경로에 swagger.js 생성

// swagger.js
// ES6문법에서 Autogen을 사용하기 위한 변형
import { createRequire } from "module";
const require = createRequire(import.meta.url);

const swaggerAutogen = require("swagger-autogen")();

const doc = {
  info: {
    title: "My API",
    description: "Description",
  },
  host: "localhost:3007",
  schemes: ["http"],
};

// 경로 = localhost:3007/swagger
const outputFile = "./swagger-output.json"; // swagger-autogen이 실행 후 생성될 파일 위치와 이름
const endpointsFiles = ["./app.js"]; //읽어올 Router가 정의되어 있는 js파일들

swaggerAutogen(outputFile, endpointsFiles, doc);

autogen은 CommonJS방식으로 작성된 패키지여서 ES6 모듈시스템에서 사용하기위해 변형시켜주어야 합니다.

 

위처럼 테스트하기 위한 경로를 다 설정해 준뒤

 

autogen을 설치했을때 생긴 swagger-output.js를 들어가서 바꿔줍니다.

{
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "description": "Description",
    "version": "1.0.0"
  },
  "host": "localhost:3007",
  "basePath": "/",
  "schemes": [
    "http"
  ],
  "paths": {
    "/": {
      "get": {
        "description": "",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/sign-up": {
      "post": {
        "description": "회원가입",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "schema": {
              "type": "object",
              "properties": {
                "email": {
                  "example": "leesonsin@gmail.com"
                },
                "password": {
                  "type": "string", 
                  "example": "123456"
                },
                "passwordCheck": {
                  "type": "string", 
                  "example": "123456"
                },
                "userName": {
                  "example": "이순신장군"
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Bad Request"
          },
          "409": {
            "description": "Conflict"
          }
        }
      }
    },
  }
}

 

위처럼 테스트할 경로, host정보를 swagger.js와 router.js에서 정의한 내용과 일치하게 적은다음

 

테스트할 내용도 적어주고 저장한다음

 

localhost:3000/swagger로 요청을 보내면

 

이렇게 정의 해뒀던 경로가 나오는걸 확인 할 수 있고

 

테스트 하기 위해 예시로 swagger-output.json에 적어뒀던 내용들을 확인할수 있고 실패시 어떤 httpstatus를 보낼지도

정의 했던 그대로 나오는걸 확인할 수 있습니다.

 

이런 테스트 항목들을 알아보기 쉽게 ui로 만들어 두면 오류가 날 위험을 방지할수도 있고 프론트와의 협업에서도

더 쉽고 직관적으로 데이터의 전달을 볼수 있어 훨씬 수월하게 협업할수 있는 방법을 알 수 있었습니다.