express와 swagger 연동하기

개요

프로젝트 진행 시 API 명세서를 문서화하여 팀원과 사용자에게 API 요청 방법에 대한 정보를 제공할 수 있어야 합니다.
기존 프로젝트에서 API 명세서를 작성할 때 swagger를 활용하여 문서화했었는데, 상단의 사진과 같이 직접 swagger의 문법을 토대로 코드를 작성하여 번거로움이 많았습니다.
하지만 개발 환경과 swagger를 연동하여, 보다 쉽게 명세서를 문서화할 수 있음을 알게되어 모바일 청첩장 프로젝트에서 활용해보게 되었습니다.

---

적용

모바일 청첩장 프로젝트의 express.js와 swagger를 연동해보았습니다.

1. swagger.ts

import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";
import { Application } from "express";

const options: swaggerJSDoc.Options = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "'우리 결혼해요' API Docs",
      version: "1.0.0",
    },
  },
  apis: ["./src/routes/*.ts"], // JSDoc 주석 경로
};

const swaggerSpec = swaggerJSDoc(options);

export function setupSwagger(app: Application) {
  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
}

우선 Swagger JSDoc 주석으로 API 문서를 자동 생성하고, express 앱에 연동하기 위한 파일을 생성합니다. 해당 파일은 config 폴더 하위에 swagger.ts 파일명으로 생성합니다.
호출한 각 모듈의 역할은 다음과 같습니다.

모듈	역할
swagger-jsdoc	JSDoc 스타일 주석을 읽어 OpenAPI 문서로 변환
swagger-ui-express	변환된 문서를 UI로 보여주는 미들웨어
options.apis	Swagger 주석이 들어간 파일 경로 설정
setupSwagger()	Express 앱에 Swagger UI 등록하는 함수

2. router.ts

/**
 * @openapi
 * /api/s3/?directory="":
 *   post:
 *     summary: S3 이미지 등록
 *     tags: [S3]
 *     parameters:
 *       - in: query
 *         name: 업로드할 directory명을 ""에 포함
 *         required: false
 *         schema:
 *           type: string
 *     requestBody:
 *       required: true
 *       content:
 *         multipart/form-data:
 *           schema:
 *             type: object
 *             properties:
 *               images:
 *                 type: array
 *                 items:
 *                   type: string
 *                   format: binary
 */

다음으로 router에서 API 메서드 및 형식을 선언해줍니다. 각 기능별 router에서 openapi를 통해 메서드와 req, res 형식을 선언합니다. 해당 내용은 서버 실행 시 브라우저의 swagger에서 확인할 수 있습니다.

3. app.ts

import { setupSwagger } from "../config/swagger";

setupSwagger(app);

마지막으로 app.ts에서 swagger.ts에서 모듈화한 함수를 호출하여 express에 등록합니다.
이로 인해 서버가 실행될 시 Swagger UI를 express앱에 등록하여 url 접근 시 swagger 문서를 조회할 수 있습니다.

---

결과

서버 실행 후 http://localhost:${PORT}/api-docs url로 접근하면 사진과 같이 swagger API 명세서를 확인할 수 있습니다.
이처럼 express 개발 환경과 swagger를 연동하여 직접 코드를 작성하지 않고, 보다 쉽게 API 명세서를 업로드할 수 있습니다.