Swagger UI 세팅 (Feat. Nodejs)

강의를 듣다가 해당 라이브러리의 존재를 알게되었다. 활용하기 좋을 것 같아서 현업에 사용 전에 정리하고자 한다.

Swagger 는 Rest API 를 위한 라이브러리이다. 매번 다른 문서 프로그램으로 API 명세서를 작성했다면 그런 노력이 조금은 줄것으로 보인다. 나또한 전에 노션으로 만들어진 API 명세서를 작성하느라 너무 번거롭고 귀찮았던 기억이 있다. 작성해놓고 내용이 조금이라도 바뀌면 또 문서가서 바꾸고.. 그런 과정을 조금이라도 잊으면 나중에 문서 꼬이고 ㅜㅜ

 

설치 및 설정

npm install swagger-cli swagger-ui-express yamljs
npm install -D @types/swagger-ui-express @types/yamljs

다운 받아주고 src 폴더 아래에 openapi.yaml 파일을 생성해준다.

openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: API
  description: 설명
  license:
    name: 이름
servers:
  - url: http://localhost:8000/PORT

#Paths api 경로 지정
paths: {}

기본적인 틀만 작성해준다. 해당 파일에선 공통되는 명세를 작성해주기 위한 용도로만 사용한다.

 

이제 index.js 혹은 app.js인 최상위 파일에 연결해줘야 한다.

import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
const path = require('path');
const swaggerSpec = YAML.load(path.join(__dirname, '../build/swagger.yaml'))
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

그 다음 package.json 파일에 명령어를추가해준다. 

"scripts": {
  "build": "tsc && node dist",
  **"api-docs": "swagger-cli bundle ./src/swagger/openapi.yaml --outfile build/swagger.yaml --type yaml",
  "predev": "npm run api-docs",**
  "dev": "nodemon"
},

npm run api-docs 가 먼저 실행되므로 swagger.yaml 파일이 자동으로 생성되고 localhost:8000/api-docs 에서 해당 파일과 관련된 swagger UI 화면을 볼 수 있다.

여기까지 기본적인 swagger 세팅이었다. 이후로는 명세서 작성을 위한 태그들을 알아야 한다.

 

Swagger 사용 방법

1. 각 파일에 주석으로 추가하는 방법
2. json 이나 yaml 파일을 사용하여 따로 관리하는 방법

두 가지가 있다. 아무래도 유지보수상 yaml 파일에 따로 정리하는 게 나은 것 같지만 그때그때마다 api 내용이 변경되면 주석을 수정해주는 게 낫지 않나 이 부분은 사용 전에 논의가 필요해보인다.

 

모든 페이지의 구조는 비슷할 것이며 yaml 파일로 작성하고자 한다면 각 기능(user / post / ...) 에 따라 파일을 달리 써주는 것이 관리가 좋아보인다. 공식문서의 예시를 보면서 가볍게 튿어보자.

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

openapi ...

스웨거의 버전을 맞춰주는 것이다. 각 버전마다 조금씩 사용법이 다르다. 

info

title 은 당연히 API 이름을 의미한다. decription 에는 API의 설명을 기재해준다.

version 또한 현재 API 버전에 맞춰 기재해줘야한다.

그밖에도 연락처, 라이선스, 약관 및 세부 정보 등의 속성도 별도로 존재한다.

servers

API 서버와 기본 URL 에 대한 상세 설명을 나타낸다. 

- 	url : 주소
	description : 설명

모든 API 경로를 서버 url에 상대적이므로 위에서 지정해준 주소가 기본 주소가 된다.

paths

엔드포인트를 작성하는 부분이다. 

상대적 주소:
	요청메서드:
    	summary: 요약 설명
        description: 설명
        response:
        	'200':
            	description: 설명
                content:
                	application/json
                    	schema:
                        	type: 타입

 매개변수, 요청 body, 응답 상태 코드 및 응답 내용 등을 작성한다. 핵심이 되는 부분이므로 https://swagger.io/docs/specification/paths-and-operations/ 직접 공식 문서를 하나씩 보자.

 

큼직한 줄기는 확인했으나 자세한 사항은 공식문서에서 태그를 확인해줄 필요가 있다. 내용이 방대하므로 꼭 확인하기 https://swagger.io/docs/specification/basic-structure/

Basic Structure