[Swagger] API 문서 자동화 프레임워크 적용기

개요

간단한 개인 프로젝트 과제를 마치고 AWS EC2에 배포까지 완료된 상황이었는데

메인 페이지가 비어있어 그냥 hello world를 넣는거보단 예전부터 해보고 싶었던 

API 문서 자동화 라이브러리를 써서 메인페이지에 API 명세서를 뿌려주면 어떨까? 라는 생각을 하게 됐다.

예전에 봤던 유튜브 영상을 언젠가 한번 해봐야지 하고 기억하고 있었다.

그래서 express + api 문서 자동화 관련 검색을 해봤는데 하나같이 다 swagger 라는걸 사용하고 있었다.

 

스웨거(Swagger)란?

- [출처]위키백과

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 
대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 
대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 
자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

 

swagger가 뭔지 알아봤으니 바로 관련 글들을 모두 보며 적용해보았다.

 

시행착오

https://development-crow.tistory.com/32

[Backend] Nodejs + Express Swagger 제대로 알고 쓰자!

npm install swagger-jsdoc swagger-ui-express

처음에는 위 블로그 포스팅대로 진행했다.

다른 블로그들에서 안내하는 .yml에서 API 문서를 복잡하고 오래걸려 만드는 방법보다

.js로 만들어 빠르고 쉽고 모듈화도 되게 만드는게 취지였던 모양인데

 

나한테는 똑같이 어렵고 복잡하고 문법도 공식문서랑 달라 오히려 더 써먹기가 힘들었다.

 

아니 자동화라며..? 이러면 어디가 자동화 인거임??

이런 생각을 하며 하던걸 내려놓고 다시 좀 더 정보를 찾아봤는데 역시

내가 원하던 swagger 자동 생성 라이브러리가 따로 존재했다.

 

swagger-autogen

https://www.npmjs.com/package/swagger-autogen

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

말 그대로 swagger를 자동 생성해주는 라이브러리이다.

사용법은 간단하다. 

swagger.js 파일을 만들어 swagger-autogen 세팅을 해준 다음

내 라우터들의 위치를 명시해놓고 swagger.js 파일을 실행하면

라우터들의 정보를 토대로 swagger-output.json 파일이 만들어진다.

(이 파일이 내가 위에서 수동으로 짜려다 포기한 그 파일이다.)

 

swagger.js

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

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

const outputFile = "./swagger-output.json";	// 같은 위치에 swagger-output.json을 만든다.
const endpointsFiles = [
  "../app.js"					// 라우터가 명시된 곳을 지정해준다.
];

swaggerAutogen(outputFile, endpointsFiles, doc);

작성했으면 저장 후 

node swagger.js

 

이렇게 만들어진  swagger-output.json 파일을 내가 원하는 path에서

실행되게 require 해준 뒤  서버를 실행하면 짠! 끝이다.

더 자세한 설명은 아래 블로그에서 보거나 맨 아래 github에서 swagger 폴더를 보면 된다. 

 

(구현하며 참고한 블로그 - https://llshl.tistory.com/49)

[NodeJS] Swagger 자동 생성 라이브러리 swagger-autogen

 

만들어주는 대로 받은 swagger-output.json으로 구현한 swagger API 페이지

 

하지만 세부 설정이 안되어 순서도 뒤죽박죽이고 열어보면 request, response 세팅도 제대로 안되어 있다.

이 부분에 대해서는 따로 잘 나와있는 곳이 없어

위에 링크 건 swagger-autogen의 npm 공식 문서를 보고 구현했는데

예시 코드는 다음과 같다.

// /posts 에 대해 post 메소드로 받는 라우터
router.post('/', async (req, res) => {
  //  #swagger.description = '게시글 작성'
  //  #swagger.tags = ['posts']
  /*  #swagger.parameters[''] = {
                  in: 'body',
                  schema: {
                      user: 'Developer',
                      password: '1234',
                      title: '안녕하세요', 
                      content: '안녕하세요 content 입니다'
                  }
  } */
  /*  #swagger.responses[201] = {
              description: '게시글 작성 성공',
              schema: {
                  message: '게시글을 생성하였습니다.'
              }
  } */
  /*  #swagger.responses[400] = {
              description: 'body 또는 params를 입력받지 못한 경우',
              schema: {
                  message: '데이터 형식이 올바르지 않습니다.'
              }
  } */
  
  // ...이후 원래 코드

 

결과물

이렇게 라우터 하나하나에 tag를 부여하고 request, response 에 대해 세세하게 작성해준 다음

swagger-output.json 파일을 만든 후 거기서 직접 더 다듬어만 주면 다음과 같은 결과물이 나오게 된다.

이런 느낌

 

시간적 여유가 있어서 해보고 싶었던 swagger API 자동화를 구현해봤는데 

힘들었지만 하면서도 너무 즐거웠다. 

내가 한글로 된 블로그 포스팅이 아닌 npm 공식 문서를 보고 기능을 구현하다니!

 

얘기를 들어보니 현업에서도 사용한다고 하고 앞으로 하게 될 과제에서도 요구 조건에 있다는 얘기를 들어

먼저 시행착오를 거쳐 구현까지 해본것에 너무 만족스럽고 뿌듯함을 느꼈다.

 

 

swagger 적용 방법에 대한 더 자세한 사항은 내 프로젝트의 github를 통해 확인해보길 바란다.

https://github.com/cchoseonghun/sparta_nodejs_posts_api

GitHub - cchoseonghun/sparta_nodejs_posts_api: 스파르타 Node.js 입문 주차 - 과제 게시판, 댓글 API

https://github.com/cchoseonghun/nodejs_blog_api

GitHub - cchoseonghun/nodejs_blog_api: 회원, 게시글, 댓글, 좋아요 기능이 있는 블로그 백엔드 API