Swagger 간단 사용법

Swagger

 

프런트엔드와 협업을 하는 과정에서 api 명세는 노션에 기록하고 있었다.

 

초반에 개발할 당시에는 api의 개수가 많지 않아 부담감이 적었지만 그 수가 많아지면서 앱서버도 개발해야하는 입장이 되자 혼자서 감당하기 힘들겠다는 생각이 들었다.

 

매번 노션에 들어가서 api의 명세를 바꾸는 것도 비효율적이라는 생각이 들었고, 혹시라도 빼먹게 되면 프런트 개발자 입장에서 매우 힘들어질 것이기 때문이다. 따라서 개발할 때는 호다닥 개발을 하더라도 후에 유지 보수를 할 때 상당한 시간 소모가 있을 것이다.

 

이런 문제를 깨닫고 분명 우리 개발자들은 무언가를 개발해 놓았을 것이다라는 생각이 들어 구글링을 해보았다.

역시!

api 명세를 위한 툴인 "swagger"라는 것이 있었고 이미 큰 기업부터 작은 스타트업까지 많은 곳에서 사용하고 있었다. 그래서 나도 도입해보기로 결정했다.

---

Swagger란?

Swagger는 무엇일까. 한마디로 정의하면 다음과 같다. (참고)

Swagger is an open source set of tools that enable you to design, build, document, and use RESTful web services.

RESTful 한 웹서비스를 디자인, 설계, 문서화 그리고 사용하는 것을 가능하게 도와주는 오픈소스 툴이다.

간단하게 말하자면 위에서 언급한 상황에서 (api 명세) 사용하는 오픈소스 툴이다.

(공식 홈페이지 에서 swagger에 대한 자세한 내용이 확인 가능하다.)

 

내가 하고 있던 프로젝트는 express(nodejs)로 백엔드 개발을 하고 있기 때문에 express 환경에서 어떻게 swagger를 적용했는지 과정을 간단하게 적어보려고 한다.

 

---

Swagger 설치 및 기본 세팅하기

npm install swagger-ui-express swagger-jsdoc --save-dev

우선 필요한 패키지를 npm을 통해 설치해준다. (개발용으로 사용하기 때문에 --save-dev 옵션을 추가해준다.)

•  swagger-ui-express: API 문서를 위한 UI 랜더링을 위한 패키지
• swagger-jsdoc: 주석에 swagger 태그를 추가하여 API 문서화하는 패키지

 

const swaggerUi = require("swagger-ui-express");
const swaggerJsdoc = require("swagger-jsdoc");

const options = {
    definition: { 
        openapi: "3.0.0",
        info: { 
            title: 'Test API', 
            version: '1.0.0', 
            description: 'Test API with express', 
        }, 
        contact: {
        	...
        },
        servers: [
            {
                url: '...',
            },
        ],
        host: 'localhost:3300', 
        basePath: '/' 
    }, 
    apis: ['../../router/*.js']
};

const specs = swaggerJsdoc(options);

module.exports = {
    swaggerUi,
    specs
};

swagger 관련 옵션을 따로 적어주기 위해 swagger.js 라는 파일을 새로 만들었다.

swagger는 yaml과 json을 지원한다고 하는데 나는 조금더 익숙한 json 형식을 선택했다.

옵션에 들어가야 하는 내용은 다음과 같다. 링크 

 

여기서 apis는 내가 설정한 api들을 swagger가 찾을 수 있도록 표시해준 것이다.

"/router 파일 아래 js 파일 내에 정의하고 있다"

 

// app.js
const { swaggerUi, specs } = require("./modules/swagger");

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs));

이제 app.js 파일로 돌아와서 위와 같이 추가해준다.

 

localhost:3000으로 띄워주고 localhost:3000/api-docs로 들어가면 위와 같이 나온다.

 

이제 본격적으로 문서화 작업에 들어가보자.

문서화를 하는것엔 두가지 과정이 있다.

1. schema 정의하기
2. api 정의하기

---

문서화하기

우선 schema부터 문서화해보자.

원하는 곳에 아래와 같이 작성한다. (yaml 표기법: 들여쓰기만을 이용해 나열하는 간단한 표기법)

나는 따로 swagger 폴더를 만들어 정의해줬다.

# /swagger/user.yml

components:
	schemas:
    	User:
            type: object
            required:
            	- usr_email
        	properties:
            	    usr_id:
                	type: integer
                        description: 유저 고유 아이디
                    usr_name:
                	type: string
                        description: 유저 이름
            example:
            	usr_email: abc@gmail.com

하나씩 뜯어보면 어떤 내용인지 감이 온다.

"User는 usr_email을 요구하고 usr_id, usr_name을 뱉는다. 각 타입은 type에 정의되어 있고 설명은 description에서 알 수 있다."

자세한 type 종류에 대해 알고 싶다면 여기서 알 수 있다.

 

이번엔 api이다.

/**
 * @swagger
 * tags:
 *  name: user
 *  description: user management
 */

우선 api를 어떤 tag에 분리할지 분류 기준을 작성해주고

/**
 * @swagger
 * path:
 * /user:
 *   get:
 *     description: 모든 유저 조회
 *     tags: [user]
 *     responses:
 *       "200":
 *         description: 조회 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: "#/components/schemas/User"
 */

GET api/user 에 대해 작성해보았다.

 

페이지를 새로고침 해줬더니

잘뜬다.

 

기본적인 세팅과 사용법은 여기까지이고

좀더 잘 활용하기 위해 사용해보면서 익혀야겠다.