[Express] swagger를 router에서 분리 정리

이전에 express 프레임워크 환경에서 작업을 하면서 api 명세를 swagger로 진행했다.

당시 swagger-ui-express와 swagger-jsdoc을 이용해 router를 작성한 코드 위해 바로 yaml형식의 swagger데이터를 데코레이터와 주석을 이용해 명세를 했었다.

이런식으로,,,

이런식으로2...

너무 마음에 안 들었다. router 영역은 몇 줄 안되는데 자세하게 명세를 하다 보면 코드가 router의 3~4배나 길게 적혔다.

그래서 방법을 찾아 swagger 명세는. yaml 파일로 분리해 리팩터링을 진행하려고 한다.

 

우선 swagger-jsdoc는 사용하지 않을 거다.

swagger-ui-express는 설치되어 있다는 전제하에 아래 모듈들을 설치해 주자

$ npm i swagger-cli yamljs

상황에 따라 dev 옵션을 추가해 설치해도 좋다.

yamljs는 yaml 파일들을 읽기 위해 사용되었고

swagger-cli는 간단하게 얘기해서 우리가 Json 또는 YAML로 작성한 Swagger/OpenAPI 파일들을 검증하고 하나의 파일로 합쳐주는 역할을 한다. 자세한 내용은 아래 링크를 참고,,,

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

 

파일 구조

나는 각 Router 파일들 마다 분리해서. yaml파일을 적어주고 싶었기에 각각 만들어줬다. 하나에 몰아서 작성해도 되지만 이왕 하는 거 분리해줬다.

여기서 고정으로 만들어줘야 되는 건 "openapi.yaml"과 "swagger.yaml" 파일이다.

openapi.yaml은 swagger라는 폴더를 만들어 넣어줬다.

역할은

1. 여러 개로 나뉘어 있는. yaml 파일들에 적혀있는 명세들을 모으는 역할

2. 중복되는 component들을 관리해주는 역할

 

공통되는 부분을 적어주는 역할이라 생각하면 된다.

 

swagger.yaml 파일은 "app.js" 파일과 동일한 레벨에 두었다. 이 파일은 빈 상태로 두면 되고 나중에 라우터 정보들을 다 입력하고 api-docs를 실행해주면 자동으로 swagger.yaml파일로 모든 내용들을 모아준다.

 

스크립트 설정

위에서 설치한 "swagger-cli"를 이용해 흩어져있는 라우터 정보들을 하나로 모아주는 스크립트를 작성해준다.

package.json에 장성을 해준다.

"scripts": {
	...
    	"api-docs": "swagger-cli bundle ./src/swagger/openapi.yaml --outfile src/swagger.yaml --type yaml",
    	...
  },

 

app.js에서 swagger 설정

import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
import path from 'path';

const swaggerSpec = YAML.load(path.join(__dirname, './swagger.yaml'));
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.use를 통해 /api-docs 에 swagger를 연결했다. 서버 url/api-docs로 접근하면 api문서를 확인할 수 있게 된다.

 

openapi.yaml작성

메인으로 작성되는 형식이며 원하는 데로 수정하면 된다.

난 아래와 같이 작성했다.

openapi: '3.0.0'
info:
  version: 0.2.0
  title: Pokemon-Collector API
  description: Pokemon-Collector API 명세서입니다
  license:
    name: MIT
servers:
  - url: http://localhost:5000/
components:
  securitySchemes:
    Authorization:
      in: header
      name: Authorization
      type: apiKey
      scheme: bearer
  security:
    Authorization: []
paths:

yaml은 귀찮은 것이 띄어쓰기를 잘해야 된다... 틀리면 찾기도 어렵고 가독성도 떨어져서 매우 귀찮다...

 

위와 같이 작성해 틀린 곳이 없다면 결과를 확인해보자

$ npm run api-docs

위 명령어를 통해 흩어져 있는. yaml 파일들을 묶어주고 서버를 실행시켜 확인해주자

경로는 "http://localhost:5000/api-docs/"로 설정했다.

성공이다. 이제 나머지 라우터 정보들을 채워준다.

 

각각의 .yaml파일에 router 정보들 채우기

잘 작성하진 않았지만 모든 파일에 형식에 맞게 다 넣어줬다. 문법은 공식문서를 보면 친절하게 잘 나와있다.

공식 문서 => https://swagger.io/docs/specification/about/

About Swagger Specification | Documentation | Swagger

 

openapi.yaml에서 $ref로 가져오기

모든 router들에 대한 정보를 입력했다면 paths 아래로 $ref들을 통해 연결을 해주면 된다.

위와 같이 넣어주었다.

보면 "#/~1", "~1"과 같이 특이한 부분이 있는데, 이는 Escape Character라고 한다. 자세한 건 역시 공식문서에 잘 나와있다.

https://swagger.io/docs/specification/using-ref/

다 작성했다면

$ npm run api-docs

위 명령어를 통해 흩어져 있는. yaml 파일들을 묶어주고 서버를 실행시켜 확인해주면 끝이다.

작성할 때마다 위 명령어를 입력하기 귀찮다면 스크립트로 작성하는 것도 하나의 방법이다.

 

Router 파일들이 매우 매우 깔끔해졌다 아주 만족한다. 따로 컴포넌트들을 정의해주지 않아 아직 완전히 정리된 건 아니지만 전보다는 가독성이 훨씬 좋아졌다.