Swagger를 활용한 API 명세와 개발 협업 2탄

0. 개요

 

💡 swagger를 명세하는 방법은 다양하다. 

 

1. 모듈을 설치해서 각각의 router 파일 상단에 직접 명세
2. yaml 파일이나 json 파일 하나에 모든 API 명세를 하는 방법

 

[ 이전 프로젝트에서 2번 방식을 선택한 이유 ]

 

개인적으로 라우터가 지저분해지는 것을 정말 싫어한다. 1번 방식은 코드가 복잡해지고 명세와 router 코드가 함께 있어 코드 가독성이 떨어졌다. 그래서 지난 프로젝트에서는 하나의 파일에 모든 API를 설계하는 방식으로 협업을 했다.

 

[ 아놔.. 어디 괄호가 잘못된거야? ] 

 

일단 yaml 파일, json 파일 두가지 모두 들여쓰기 또는 괄호가 중요하다.

그런데 점점 API가 많아질수록 괄호나 들여쓰기 실수가 발생했을 때 오류를 찾는 과정이 정말 피곤했다.. (정말정말) 🤣

 

 

사라진 괄호를 찾아서..! 시간이 너무 아까웠다.

 

[ 코드를 분리하고 싶어! ]

 

따라서 이번엔 yaml 파일로 paths를 분리하여 명세를 하고 완벽하게 완성이 돼서 프론트 단에서 확인이 필요할 때는 merge 하는 방식을 사용하고자 한다.

 

 

📌 지난 포스팅

• Swagger를 활용한 API 명세와 개발 협업
• 지난 swagger 문서 보러가기

 

---

Swagger로 API 명세하기

< 폴더 구조 >

 

 

1. 설치

yarn add swagger-cli swagger-ui-express yamljs
yarn add -D @types/swagger-ui-express @types/yamljs

 

개발, 배포 모두 swagger를 사용하기 때문에 위의 패키지는 devDependencies로 설치하지 않았다.

 

2. openapi.yaml

 

이제 모든 명세는 해당 파일에 한다.

이때 paths로 명세를 하게 되는데 API가 많아지면 가독성이 떨어지기 때문에 

paths만 따로 파일 분리를 했다.

 

openapi: 3.0.1
info:
  version: 1.0.0
  title: Web API docs
  description: team 17 API 문서입니다
  license:
    name: MIT
servers:
  - url: http://localhost:5000/

 

openapi.yaml 파일에 paths를 다음과 같이 작성한다.

 

paths:
  $ref: './paths/_index.yaml'

 

그리고 paths 폴더 아래 파일을 만들어서

 

다음과 같이 paths 코드만 작성하면 된다.

/:
  get:
    summary: Main Page
    responses:
      400:
        $ref: '../openapi.yaml#/components/responses/BadRequest'

 

3. app.ts

swagger-ui와 app.ts를 연결한다.

다음 코드는 app.ts에서 swagger를 연결하기 위한 코드이다.

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

const swaggerSpec = YAML.load(path.join(__dirname, './swagger/swagger.yaml'));

// swagger
app.use('/swagger', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

 

4. package.json

 

"scripts": {
    "start": "nodemon --exec ts-node index.ts",
    "swagger": "swagger-cli bundle ./src/swagger/openapi.yaml --outfile ./src/swagger/swagger.yaml --type yaml"
  }

 

 

모두 설정한 후 openapi.yaml 파일에 작성한 코드를 yarn swagger를 해주면 (위 스크립트) 보기 편한 형식으로 swagger-cli가 swagger.yaml 파일을 만들어준다.

 

app.ts에서 swagger.yaml 파일에 연결되어 있다.

 

따라서 yarn start 해서 'http://localhost:5000/swagger'로 들어가면 

 

 다음과 같이  명세를 확인할 수 있다.

 

 

 

swagger를 사용하면 배포했을 때 명세를 바로 찾아볼 수 있어 편리하다. 

또한 변경된 코드를 빠르게 프론트에서 test 해볼 수 있어 유용하다.

 

 

---

📌 Reference

• Node.js (TS) 프로젝트에 swagger 적용하기