Swagger

zioo·2022년 2월 21일

Backend

목록 보기

34/40

Swagger란

Swagger(스웨거)는 개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 하는 프로젝트이다.

스웨거는REST API를 문서화하는 도구이다.
API에 대한명세(Spec)을 관리하기 위한 프로젝트이다.
API가 수정되더라도문서가 자동으로 갱신된다

Swagger는 Open API Specification(OAS)를 위한 프레임워크입니다. 간단한 설정으로 프로젝트에서 지정한 URL들을 HTML 화면으로 확인할 수 있게 해주는 프로젝트입니다. Swagger를 활용해서 API 명세를 작성한다면, 보다 쉽게 API 명세를 작성할 수 있습니다.

왜 사용할까?

Swagger를 사용하는 이유는 다음과 같다.

협업을 진행하거나 이미 만들어져 있는 프로젝트에 대해 유지보수를 진행하게 된다면 구축되어 있는 API가 어떤 스펙을 갖고 있는지 알아야 합니다. 스펙을 정리하기 위해 API 문서화 작업을 해야 하는데, 만약 직접 손으로 하게 되는 경우 API를 개발하기 전에 API의 명세와 문서를 작성하고, API가 수정될 때마다 문서도 같이 수정해야 하는 번거로움이 발생합니다. 이런 불편함을 조금이나마 줄여주기 위해 개발된 것이 Swagger 프레임워크입니다.
만약 API 명세를 제대로 작성하지 않는다면 어떤 문제가 발생할 수 있을까요?

API 명세서가 전혀 존재하지 않아서, 코드를 전부 확인하는 과정에서 개발 시간이 너무 오래 걸립니다.
클라이언트 개발자는 서버 개발자에게 API가 어떻게 동작하는지 물어보면서 개발해야 합니다.
개발할 때는 시간이 적게 걸릴 수 있지만, 유지 보수를 할 때, 시간이 상당히 오래 걸립니다.

이 같은 문제를 swagger를 통해 해결할 수 있습니다. 그렇다면, Swagger를 어떻게 적용시킬 수 있을까요?

Swagger 기본 설정

swagger-jsdoc과 swagger-ui-express 라이브러리를 활용한 개발 방법을 택했습니다.

기존 서버 route에서 바로 코드를 작성할 수 있기 때문에 관리가 쉽다
접근성이 가장 좋음
컴포넌트를 별도로 구분해서 관리할 수 있어서 관리하기 쉽고, 사용하기 편리하다

swagger를 적용하기 위해서는 npm 모듈을 설치하고, 그 이후에 swagger에 대한 옵션 등을 설정해야 합니다. 그리고 path를 설정해서 자신의 IP에서 확인할 수 있도록 설정해야 합니다.

npm mudule 설치

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

swagger는 개발용 모듈이기 때문에 devDependencies에 추가해줘야 합니다. 그래서 --save-dev 옵션을 붙였습니다.

Options

먼저 Basic Structure에 대해 설정

프로젝트 구조와 파일 형식은 다 다르겠지만, 저는 modules라는 폴더에 swagger.js 파일을 만들었습니다.


const swaggerUi = require('swagger-ui-express');
const swaggereJsdoc = require('swagger-jsdoc');

const options = {
    swaggerDefinition: {
        info: {
            title: 'Test API',
            version: '1.0.0',
            description: 'Test API with express',
        },
        host: 'localhost:3300',
        basePath: '/'
    },
    apis: ['./routes/*.js', './swagger/*']
};

const specs = swaggereJsdoc(options);

module.exports = {
    swaggerUi,
    specs
};

모듈을 불러오고, 옵션을 설정한 내용들 뿐이지만,
swaggerDefinition는 yaml 형식이나 json 형식을 받습니다. 위는 json을 사용했습니다.

info 객체는 title, version, description을 설정했습니다.

apis는 내가 설정한 api들을 swagger가 찾을 수 있도록 표시해줍니다. "/routes 파일 아래 js 파일 내에 정의하고 있으며, /swagger 폴더 아래 swagger 설정을 정의하고 있다"를 명시해준 것입니다.

이제 기본 설정이 끝났으니 적용시켜보겠습니다.

app.js, 라우팅 설정

app.js에서 먼저 swagger.js를 불러옵니다.

const { swaggerUi, specs } = require('./modules/swagger');

그리곤, /api-docs라는 path로 등록시켜줍니다.

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

이 부분은 모든 path를 정의하기 전, (express에서는 indexRouter 윗부분)에 정의하는 게 좋겠습니다. 여기까지 했다면 설정은 끝났고, 실행해보면 /api-docs에 아래와 같이 뜨는 것을 확인할 수 있습니다.

Swagger 정의

API 등록

routes 폴더의 route에서 swagger를 적용해봅시다.

swagger를 기존 js 파일에 적용하려면 @swagger를 반드시 붙여줘야 합니다. 그 아래에는 /product가 있는데요. 이는 경로를 나타냅니다. 경로를 설정하는 데에는 몇 가지 방법을 확인할 수 있습니다.

/**
 * @swagger
 *  /product:
 *    get:
 *      tags:
 *      - product
 *      description: 모든 제품 조회
 *      produces:
 *      - application/json
 *      parameters:
 *        - in: query
 *          name: category
 *          required: false
 *          schema:
 *            type: integer
 *            description: 카테고리
 *      responses:
 *       200:
 *        description: 제품 조회 성공
 */
router.get('/', getList);

경로 설정

아주 기본적으로 /path 만을 적을 수 있습니다.
파라미터를 넣을 수 있습니다. /path/{path_parameter_name} 파라미터를 설정하려면, 위의 코드에서 parameters 아래에 in:path로 설정하면 됩니다.
query를 추가할 수도 있습니다. /path/query=q1 이 형태는 어떻게 표시해야 할까요? parameters 아래 보면 in: query를 확인할 수 있습니다.

메서드

그 아래에는 메서드를 get, post, put, delete 등등을 설정합니다.

그 밖의 통신 규칙과 설명

그 아래에는 다양한 설정들을 볼 수 있습니다. tags는 해당 API의 태그인데요. /api-docs 페이지에서 그 태그 별로 리스팅 해줍니다.

description는 해당 API를 설명하고, produces는 content-type을 명시합니다. parameters, requestBody, responses 등이 있습니다. 내부 정의 내용은 비슷하니 아래 링크를 보고 공부해야 합니다.

https://swagger.io/specification/

컴포넌트 정의

routes 폴더와 같은 위치에 swagger 폴더를 만들어서 product.yaml 파일을 만듭니다. yaml은 JSON과 XML과 같이 데이터 직렬화 양식이지만 들여쓰기만을 이용해서 나열하는 아주 간단한 표기법입니다. 이를 활용해서 components를 정의해보겠습니다.

# /swagger/product.yml

components:
  schemas:
    Product:
      properties:
        id:
          type: integer
          description: 제품 고유 번호
        title:
          type: string
          description: 제품 이름
        main_image:
          type: string
          description: 제품 메인 이미지
        discount:
          type: integer
          description: 할인 내역

path 정의와는 다르게 components로 시작합니다. 이렇게 정의해두고 api의 결과 객체를 설명해줄 수 있습니다. 위의 파일을 적고 나서 가장 중요한 건, api 설정에 추가해줘야 한다는 점입니다.


/**
 * @swagger
 *  /product:
 *    get:
 *      // ... 
 *      responses:
 *       200:
 *        description: 제품 조회 성공
          // 아래 schema 추가
 *        schema:
 *          $ref: '#/components/schemas/Product'
 */
 router.get('/', getList);

그 후 routes.js에서 위에서 작성한 것에서 schema를 추가합니다. schema: $ref를 추가해서 swagger를 명시합니다.