express에서 swagger 사용한 기록

Backend를 정말 오랜만에 한다.
솔직히 경력으로 따졌을 때는 경력이라고 할게 없었다.

이번에 gcode finder를 개발을 해보면서, swagger를 꼭 도입을 해야겠다라고 생각을 했다.
솔직히 API 문서정리는 꼭 필요한 것이지만 귀찮아서 차일피일 미루다보면 걷잡을 수 없는 상황이 발생을 한다.

회사에서 사용을 한다면 하겠지만 우리 팀에서 작업을 할 때는 뭔가 건너 뛸 것 같은 느낌이라서 귀찮더라도.. 꼭..

일단 사용한 라이브러리는 두개이다.

const swaggerUi = require("swagger-ui-express");
const swaggerJSDoc = require("swagger-jsdoc")


$ npm install swagger-jsdoc swagger-ui-express

설치와 설정이 너무 간단하다.

const swaggerDefinition = {
  info: {
    // API informations (required)
    title: "Gcode finder API", // Title (required)
    version: "1.0.0", // Version (required)
    description: "Gcode finder express api server.", // Description (optional)
  },
  license: {
    name: "Hyelim's code store license",
    description: "",
    url: "",
  },
  contact: {
    name: "Hyelim's code store",
    url: "",
    email: "hyelim.code.store@gmail.com",
  },
  basePath: "/api", // Base path (optional)
};

const options = {
  swaggerDefinition: swaggerDefinition,
  apis: ["./routes/**/*.js"],
};
const swaggerSpec = swaggerJSDoc(options);


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

위 처럼 하기만하면 된다.

실제 API문서 작성시에는 아래와 같다.

/**
 * @swagger
 * /user/login:
 *  post:
 *    summary: "유저 로그인"
 *    description: "id, password 필수 입력"
 *    tags: [Users]
 *    parameters:
 *      - in: body
 *        name: login
 *        required: true
 *        description: 로그인 정보
 *        schema:
 *          type: object
 *          required:
 *            - user_id
 *            - user_password
 *          properties:
 *            user_id:
 *              type: string
 *              example: luyoes20
 *            user_password:
 *              type: string
 *              example: qweqwe12312
 *    responses:
 *      "200":
 *        description: 사용자가 서버로 전달하는 값에 따라 결과 값은 다릅니다. (유저 조회)
 *        content:
 *          application/json:
 *            schema:
 *              type: object
 *              properties:
 *                ok:
 *                  type: boolean
 *      "404":
 *        description: 사용자가 검색시 데이터가 없거나, 잘못된 url을 호출 하는 경우에 발생합니다.
 *        contents:
 *          application/json:
 *            schema:
 *              type: object
 *              properies:
 *                ok:
 *                  type: boolean
 */

혹시 몰라서 아래의 공식 문서 링크를 같이 남긴다.

Ps 언젠가 또 검색을 할 것 같아서 메모

swagger.io/docs/
editor.swagger