본문 바로가기
Research/Tool

API_Swagger auto-gen 적용기

by RIEM 2023. 1. 15.

들어가기

7일짜리 미니 프로젝트에 Swagger를 적용하여 팀원분들이 편리하게 API를 확인할 수 있는 명세를 만들고 싶었다. 물론 구글시트로 상세하게 명세를 해두었긴 했지만, 직접 요청할 수 있는 Swagger를 사용해보고 싶은 마음이 컸다. 하지만 Swagger를 사용하려면 한땀한땀 주석을 달아야한다는 것을 보고 7일짜리 프로젝트에 적절한 시도일까라는 의문이 들 때 즈음 Swagger auto-gen을 알게되었다.

배경 지식

sswagger auto-gen 작동 원리의 핵심은?

  • Swagger auto-gen에게 router의 경로를 알려주면 하위 router을 알아서 추적하여 자동으로 api 명세서를 위한 json 파일을 생성해주는 원리다.

프로세스

  1. swagger.js 실행 : package.json prestart 스크립트로 swagger.js 실행. 지정된 경로 내 라우터와 swagger 주석을 읽는다
  2. 실행 결과, swagger 문서 구조를 나타내는 swagger-output.json 파일이 생긴다.
  3. 생성된 json파일 바탕으로 swagger API 명세서가 생긴다

준비

npm 모듈 설치

npm i swagger-ui-express swagger-autogen

app.js에 모듈 불러오기

const swaggerUi = require("swagger-ui-express");
const swaggerFile = require("./swagger-output");


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

root 디렉터리에 swagger.js 파일 추가

// swagger.js
const swaggerAutogen = require("swagger-autogen")();

const doc = {
  info: {
    title: "99_miniproject_내가기린그림",
    description: "맞춰보시오",
  },
  host: "localhost:3000",
  schemes: ["http"],
};

const outputFile = "./swagger-output.json";
const endpointsFiles = ["./app.js"];

swaggerAutogen(outputFile, endpointsFiles, doc);

swagger-autogen 명령어 실행

 node ./swagger.js

또는 package.json에 script 추가

    // { ... },
    "scripts": {
        // ... ,
        "swagger-autogen": "node ./swagger.js"
    }

사용

실행 node ./swagger.js 또는 npm run swagger-autogen(script 추가했을 경우)

  • swagger-autogen 명령어를 실행하면 swagger-output.json 파일이 생긴다. 그러면 이제 위 swagger.js에서 정의한 host 주소에 /swagger 를 붙인 url로 접속하면 swagger API 명세서를 볼 수 있다.

접속 localhost:3000/swagger

상세 설명

Swagger API 주소로 접속하면 최소한의 정보만 표현되어있다. 위의 이미지는 내가 간단한 태그와 method에 대한 요약 정보를 추가한 것이다.

swagger 주석을 추가로 작성하면 더 풍부한 API 명세를 만들면 된다. 주석을 쓰는 방법과 양식은 공식 깃허브 사이트를 참조하며 된다.

평가

이번에는 swagger-autogen을 사용하여 적용해보았다. autogen은 swagger 기초 골격을 빠르게 자동으로 세워준다는 장점이 있지만 상세한 API 명세까지는 표현해주지 못하는 것이 한계다. 따라서 swagger-autogen으로 골격을 먼저 만든 뒤, 디테일한 정보는 swagger 주석을 따로 추가하는 방식으로 활용하면 된다.

참고

공식

블로그

저작자표시

'Research > Tool' 카테고리의 다른 글

How to remove un-used imported package automatically in Visual Studio Code  (0) 2023.09.22

관련글

댓글

티스토리툴바