swagger로 api 문서화 하기

app.js

import express from "express";
import helmet from "helmet";
import morgan from "morgan";
import cors from "cors";
import tweetController from "./tweet/tweet.controller.js";
import authController from "./auth/auth.controller.js";
import { config } from "../config.js";
import sequelize from "../database.js";
import csrf from "./middleware/csrf.js";
import rateLimiter from "./middleware/rate-limiter.js";
import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

// 서버 생성
const app = express();

// 미들웨어
app.use(csrf);
app.use(express.json());
app.use(morgan("dev"));
app.use(helmet());
app.use(cors());
app.use(rateLimiter);

// swagger definition
const swaggerDefinition = {
  openapi: "3.0.0",
  info: {
    title: "Twitter",
    version: "1.0.0",
    description: "유석현의 Twitter",
  },
  servers: [
    {
      url: "http://localhost:8000",
    },
  ],
};

// options for the swagger docs
const options = {
  // import swaggerDefinitions
  swaggerDefinition,
  // path to the API docs
  apis: ["src/**/*.js"],
};

// initialize swagger-jsdoc
const swaggerSpec = swaggerJSDoc(options);

// serve swagger
app.get("/swagger.json", (req, res) => {
  res.json(swaggerSpec);
});

// api 문서
app.use(
  "/api-docs",
  swaggerUi.serve,
  swaggerUi.setup(swaggerSpec, {
    explorer: true,
  })
);

// 라우터
/**
 * @swagger
 * tags:
 *  name: Tweet
 *  description: 트윗 관련 API
 */
app.use("/tweet", tweetController);
app.use("/auth", authController);

// 404 에러 핸들러
app.use((req, res, next) => {
  res.sendStatus(404);
});

// 500 에러 핸들러
app.use((err, req, res, next) => {
  res.sendStatus(500);
});

// DB 연결
sequelize.sync().then(() => {
  // 8000 포트로 listen
  // DB가 연결된 다음에 서버 실행
  app.listen(config.port, () => {
    console.log("Server On...");
  });
});

tweet.controller.js

import express from "express";
import * as tweetService from "./tweet.service.js";
import { body } from "express-validator";
import { validate } from "../middleware/validator.js";
import { auth } from "../middleware/auth.js";

const tweetController = express.Router();

const textValidator = [
  body("text")
    .trim()
    .isLength({ min: 5 })
    .withMessage("text를 최소 5 글자 이상 입력해주세요."),
  validate,
];

// 전체 조회
/**
 * @swagger
 *
 * /tweet:
 *   get:
 *     tags:
 *      - Tweet
 *     summary: tweet 전체 조회
 *     description: tweet을 배열 형태로 return 한다
 *     responses:
 *       200:
 *         description: An array of tweets
 */
tweetController.get("/", auth, tweetService.getTweets);

// 상세 조회
tweetController.get("/:id", auth, tweetService.getTweet);

// 트윗 생성
tweetController.post("/", auth, textValidator, tweetService.createTweet);

// 트윗 수정
tweetController.put("/:id", auth, textValidator, tweetService.updateTweet);

// 트윗 삭제
tweetController.delete("/:id", auth, tweetService.deleteTweet);

export default tweetController;

GET: http://localhost:8000/api-docs