[Node.js] swagger로 api 문서 자동화하기

api를 문서화하고 있었는데, 매번 일일이 치기 귀찮다. 시간도 많이 드는데 하나씩 언제 치고 있는가. 그래서 자동화하는 라이브러리를 봤다가 시도했다가 실패했다. 그래서 머리 아파서 나중에 하자.

지금이 그 나중이다.

설치하기

npm install swagger-jsdoc swagger-ui-express swagger-autogen

• swagger-jsdoc : json으로 만들어진 파일을 가지고 openAPI 사양을 생성한다.
• swagger-ui-express : express에서 swagger.json를 기반으로 swagger-ui를 생성해준다.
• swagger-autogen : swagger를 자동 생성해주는 라이브러리이다.

swagger.js 셋팅하기

1) 구조 살피기

// 프로젝트 구조
├ src
└─ swaggerFile
	└─ swagger.js      
	└─ swagger-output.json     
└─ app.js
└─ api
	└─ like.js      
	└─ oauth.js      
	└─ question.js      

2) swagger.js 셋팅하기

const swaggerAutogen = require('swagger-autogen')({ language: 'ko' });

const doc = {
  info: {
    title: "타이틀 입력",
    description: "설명 입력",
  },
  host: "host 주소 입력",
  schemes: ["http"],
  // schemes: ["https" ,"http"],

const outputFile = "./swaggerFile/swagger-output.json";
// 위에서 설정한 위치에 swagger-output.json을 만든다.
const endpointsFiles = ["../api/*"];// 라우터가 명시된 곳을 지정해준다.

swaggerAutogen(outputFile, endpointsFiles, doc);

• swagger-autogen를 import해준다.
• swagger-ui를 생성해주기 위하여 doc를 설정해준다.
  • doc에는 기본적인 정보를 제공해준다.
• outputFile, endpointsFiles를 셋팅해준다.
  • outputFile : swagger.js가 돌아가면 자동으로 내가 설정한 경로에 swagger-output.json이라는 이름으로 생성된다.
  • endpointsFiles : 라우터들이 생성된 경로를 지정한다. 이를 가지고 swagger-output.json이 생긴다.

3) app.js 설정하기

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

//Swagger
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerFile, { explorer: true }));

위의 코드를 app.js에 붙여주었다.

4) package.json 셋팅하기

//package.json
"scripts": {
    "test": "cross-env NODE_ENV=test jest",
    "testing": "nodemon tests/products.test.js",
    "start": "nodemon app.js",
    "swagger": "node ./swaggerFile/swagger.js"
  },

자주 써줄 것 같아서 package.json에서 swagger라는 이름으로 돌아갈 수 있도록 설정해주었다.

5) swagger.js 실행시키기

npm run swagger

package.json에서 명령어를 설정해주었기에, 위의 코드를 쳐서 swagger.js가 실행될 수 있도록 한다. 그러면 아래와 같이 나온다.

swagger success

6) backend 실행시키기

npm run start

명령어를 쳐서 app.js가 구동되게 하면 /api-docs에 들어가면 내가 설정한 api들을 한 눈에 확인할 수 있다.

웹사이트에 대한 api문서

디테일 손보기

위와 같이 swagger UI를 확인할 수 있다. 그래서 질서있게 정리할 필요가 있다.

그래야 나중에 가독성있게 볼 수 있기 때문이다.

//api/like
router.post("/like/:id", async (req, res) => {
//  #swagger.tags = ['Like API']
  //  #swagger.summary = 'id별 like하기'
  //  #swagger.description = 'id별로 좋아요, 삭제합니다.  '
# 원래 본인의 코드

→ 내 경우, tags, summary, description만 추가해주었다. 본인이 원하는 태그만 추가해줘도 된다.

결과화면

결과 화면

api 상세내용

👇🏻 참고 사이트

https://llshl.tistory.com/49

https://4sii.tistory.com/206