[node.js] Swagger 자동 생성 라이브러리 swagger-autogen 적용 예제

서론

https://github.com/davibaltar/swagger-autogen

davibaltar/swagger-autogen

swagger-autogen이라는 아주 좋은 라이브러리를 발견했다. 위 주소의 공식문서를 읽어보면 현재 구현되어 있는 라우터들의 모듈 별 엔드 포인트를 식별하고 응답 상태 코드, 바디 파라미터, 경로의 매개 변수, 쿼리 등을 전부 식별하여 Swagger document 구성을 자동으로 수행하여 swagger에서 읽을 수 있는 형식의 json 파일을 생성해주는 라이브러리이다. 

예제

위 라이브러리에서 기본으로 제공하는 example 코드를 통해 예제를 구현하고자 한다.

먼저 예제코드 https://github.com/davibaltar/example-swagger-autogen-with-router.git 을 클론 후 모듈을 받아준다.

$ npm install

그 후 아래 명령을 사용하여 현재 nodejs 프로젝트의 엔드포인트들의 swagger를 자동으로 생성한다.

$ npm run start-gendoc

명령을 실행하면 src/endpoints.js 에 있는 Router들이 자동으로 인식되어 스웨거에서 읽을 수 있는 swagger_output.json 파일로 생성된 것을 확인할 수 있다.

$ npm start

프로젝트를 실행하면 http://localhost:3000/doc 에 swagger가 자동으로 설정된 것을 확인할 수 있다. 만약 해당 swagger-autogen을 내가 개발 중인 프로젝트에 적용하는 방법을 알아보고자 한다. 

적용

먼저 해당 프로젝트에 모듈을 다운로드 한다.

$ npm install swagger-ui-express
$ npm install swagger-autogen

그리고 프로젝트의 app.js 에서 아래와 같이 추가한다.

//상단에 삽입
const swaggerUi = require('swagger-ui-express')
const swaggerFile = require('./swagger_output.json')


//하단에 삽입
app.use('/swagger', swaggerUi.serve, swaggerUi.setup(swaggerFile)) // docs 대신 swagger로 수정한다.

방금 예제에 있던 swagger.js 파일을 프로젝트 루트 디렉터리로 옮긴 뒤 아래와 같이 수정한다. 주의할 점은 꼭 .then 코드를 삭제한다.

const swaggerAutogen = require('swagger-autogen')()


const doc = { ... } // 본인의 설정으로 수정한다.

const outputFile = './swagger_output.json' // swagger-autogen이 실행 후 생성될 파일 위치와 이름
const endpointsFiles = ['./routes/users.js', './routes/s3.js', './routes/verify.js'] // 읽어올 Router가 정의되어 있는 js파일들

//아래 코드에 .then() 이후를 삭제한다.
swaggerAutogen(outputFile, endpointsFiles, doc);

방금 swagger.js에서 .then()에 적용되어 있는 콜백으로 서버를 켜주는 코드를 삭제했기 때문에 위 코드를 실행해도 서버가 실행되지 않는다. 그래서 서버가 실행되기 전에 항상 자동으로 실행할 수 있게 package.json을 수정하고자 한다.

//package.json 의 scripts 부분

"scripts": {
	"start": "node ./bin/www", // 해당 부분은 수정하지 않는다.
	"prestart": "node ./swagger.js" // 이 부분만 추가한다.
 },

scripts 명령 prestart에 swagger-autogen을 실행시키는 코드를 삽입하게 되면 start가 되기 전에 자동으로 prestart 를 실행시켜주게 된다. 이제 이전과 똑같이 서버를 구동시킨다.

$ npm start

정상적으로 start가 되기 전에 swagger-autogen이 실행 후, swagger_output.json 파일이 생성되고 서버가 실행되는 모습이다.
이제 도메인/swagger 주소로 접속하면 자동으로 만들어진 swagger를 확인할 수 있다.