728x90
반응형
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가 실행될 수 있도록 한다. 그러면 아래와 같이 나온다.
6) backend 실행시키기
npm run start
명령어를 쳐서 app.js가 구동되게 하면 /api-docs에 들어가면 내가 설정한 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만 추가해주었다. 본인이 원하는 태그만 추가해줘도 된다.
결과화면
👇🏻 참고 사이트
728x90
반응형
