Swagger

하나의 서비스를 완성하기 위해선 수많은 개발자들이 투입된다. 그렇기 때문에 개발을 함에 있어서 협업은 굉장히 중요하다.

백엔드 엔지니어가 API를 만들면 프론트엔드 엔지니어가 해당 API를 활용해야 하기 때문에 그에 대한 정보 공유가 필수다. 따라서 백엔드 엔지니어는 각각의 API가 어떤 매개변수를 입력받아서 어떤 결과를 내놓는지 등의 API 스펙에 관한 문서를 만든다. 하지만 이것을 워드나 엑셀로 만든다면 만드는 사람도 상당히 귀찮고 그것을 확인하는 입장에서도 굉장히 불편하다.

따라서 보다 편하게 API문서를 자동으로 관리할 수 있도록 나온 것이 swagger다.

 

swagger 공부를 처음 시작할 때 참고하기 좋은 사이트가 있다. Swagger에서 자체적으로 개발자들을 위한 Editor을 오픈해두었다 : editor.swagger.io/

 

그럼 지금까지 작업한 API를 가지고 swagger 페이지를 만들어 보겠다.

 

우선 express 프레임워크에서 swagger를 사용하기 위해 설치해주어야 하는 모듈이 2가지 있다.

1. npm install --save swagger-ui-express : swagger 화면에 뜨는 ui를 사용할 수 있는 모듈

2. npm install --save swagger-jsdoc : swagger 화면 설정을 javascript 형식에서 할 수 있도록 해주는 모듈

(현재 시점 기준으로 swagger-jsdoc을 설치하면 7.0.0 버전이 설치되는데 호환성 문제가 있어서 6.0.6버전으로 낮춰줘야 한다)

 

모듈을 모두 설치하고 난 후 swagger를 사용하기 위한 세팅을 app.js에 해주었다.

기본적인 information 그리고 swagger파일을 불러오기 위한 경로 설정들을 해준다. 나는 swagger파일들은 schemas라는 폴더 안에 따로 만들어 주었다.

 

본격적인 swagger 코드를 보자.

swagger의 시작과 끝 : /** */ 으로 열고 닫아준다.

@swagger로 해당 파일이 swagger 파일이라는것을 명시해주고 아래 그림과 같이 명명해준다.

javascript를 활용해서 swagger 문서를 작성할 때 주의할 점은 하위 카테고리로 들어갈 때 앞쪽에 두칸씩 띄워주어야 한다.

/**
 * @swagger
 * /cart:
 *   get:
 *     tags:
 *       - Cart
 *     name: Get Cart
 *     summary: Get Cart
 *     parameters:
 *       - name: cart_idx
 *         in: query
 *         schema:
 *           properties:
 *             type: number
 *       - name: user_idx
 *         in: query
 *         schema:
 *           properties:
 *             type: number
 *     responses:
 *       '200':
 *         description: Get Cart
 *       '404':
 *         description: fail
 */

parameters 위쪽 부분까지는 ui를 어떻게 나타낼지 설정하는 부분이다.

<swagger ui>

내부에 들어가는 parameters 설정은 이름을 명명하고 해당 파라미터를 어떤 방식으로 받아올지에 대해서 in에 입력해준다. query, body 등 여러 가지 형식으로 받아올 수 있다. 그리고 그 파라미터에 대한 내용을 정의할 때 schema를 사용하고 그 안에서 properties로 세부적인 설정을 해준다.

 

위의 코드로 작성한 get 페이지는 다음과 같이 표시된다.

 

실제로 작성한 swagger코드와 전체 화면을 더 보고 싶다면 github에서 확인 가능하다.