Swagger 사용 (feat. express)

팀 프로젝트를 진행하게 되면서 api 명세서를 만들게 되었다.
swagger를 한번 써보자고 이야기가 나와서 개인적으로 만들고 있는 boilerplate에 적용해보기로 함.
참고로 필자는 swag이 없다 ㅎㅎ

0. 디렉터리 구조

들어가기에 앞서 내 디렉터리 구조

 server
    ├── babel.config.json
    ├── index.js
    ├── package-lock.json
    ├── package.json
    └── src
        ├── app.js
        ├── config
        │   └── strategies
        │       ├── LocalStrategy.js
        │       └── jwtStrategy.js
        ├── controllers
        │   └── userController.js
        ├── db.js
        ├── models
        │   ├── index.js
        │   └── schemas
        │       └── userSchema.js
        ├── routes
        │   └── userRouter.js
        ├── services
        │   └── userService.js
        └── swagger
            └── swagger.js

1. 라이브러리 설치

npm install swagger-ui-express swagger-jsdoc

2.swagger.js - swagger options 설정

import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const options = {
  swaggerDefinition: {
    openapi: "3.0.0",
    info: {
      version: "1.0.0",
      title: "API",
      description: "user bolier plate",
    },
    servers: [
      {
        url: "http://localhost:5000", // 요청 URL
      },
    ],
  },
  apis: ["./src/routes/*.js"], //Swagger 파일 연동
};

const specs = swaggerJSDoc(options);

export { swaggerUi, specs };

apis 에는 @swagger를 달아주는 파일의 경로를 써주면 된다.
처음에는 상대경로 인 줄 알고 ../routes/*.js를 해줬는데 아래 사진같은 현상이 발생했고
찾아보니 apis는 소스파일이 들어있는 제일 위의 폴더부터 절대경로로 써주면 된다고 한다.

3. app.js

import { swaggerUi, specs } from "./swagger/swagger";

먼저 swagger.js에서 export 해준 swaggerUi,specs를 import 해준다.

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs));

그리고 해당 코드 추가 app이 listen()하기 전에 써줘야한다고 한다.
이때 /api-docs는 api 명세서 페이지로 들어가는 url엔드포인트
localhost:포트번호/api-docs 로 접속해주면 됨.

app.js 전체코드

import express from "express";
import cors from "cors";
import { userRouter } from "./routes/userRouter";
import passport from "passport";
import { jwt } from "./config/strategies/jwtStrategy";
import { swaggerUi, specs } from "./swagger/swagger";

const app = express();

app.use(cors());

app.use(express.json());
app.use(express.urlencoded({ extended: false }));

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs));

app.use(passport.initialize());
// passport.use(local);
passport.use(jwt);

app.get("/", (req, res) => {
  res.send("env 적용");
});

app.use("/users", userRouter);

export { app };

나는 app.js를 export 해서 index.js에서 import 해와서
index.js에 app.listen()을 넣어줬음

4. UserRouter.js

/**
 * @swagger
 * tags:
 *   name: UserJoin
 *   description: 유저 회원가입
 */
userRouter.post("/join", joinUser);

애노테이션을 swagger로 사용해줘야함!!
@swagger

여기까지 진행하고 localhost:포트번호/api-docs로 들어가주면 아래 사진처럼 뜬다.

바꿔줘도 잘 실행됨 ㅎㅎ