node.js에 swagger 적용

Spring Boot에 적용했었던 swagger를 node.js에도 적용해보자.

spring boot에서는 자동으로 만들어졌으나, node.js에서는 Definition을 적용해줘야해서 귀찮다.
설정 방법을 알아보자.

설치 패키지

"swagger-jsdoc": "^3.0.2",
"swagger-ui-express": "^4.0.0"

Definition정의

swagger에 대해 적용할 프로그램에 대한 정보와 path, api들 위치등에 대해 정의한 definition을 정의한다.

/**
 * Created by wedul on 2018. 8. 30.
 */
'use strict';
 
module.exports = {
  swaggerDefinition: {
    // 정보
    info: {
      title: 'node js test app',
      version: '1.0.0',
      description: 'Make For node js test.'
    },
    // 주소
    host: "localhost:3000",
    // 기본 root path
    basePath: "/",
    contact: {
      email: "rokking1@naver.com"
    },
    // 각 api에서 설명을 기록할 때 사용할 constant들을 미리 등록해놓는것
    components: {
      res: {
        BadRequest: {
          description: '잘못된 요청.',
          schema: {
            $ref: '#/components/errorResult/Error'
          }
        },
        Forbidden: {
          description: '권한이 없슴.',
          schema: {
            $ref: '#/components/errorResult/Error'
          }
        },
        NotFound: {
          description: '없는 리소스 요청.',
          schema: {
            $ref: '#/components/errorResult/Error'
          }
        }
      },
      errorResult: {
        Error: {
          type: 'object',
          properties: {
            errMsg: {
              type: 'string',
              description: '에러 메시지 전달.'
            }
          }
        }
      }
    },
    schemes: ["http", "https"], // 가능한 통신 방식
    definitions:  // 모델 정의 (User 모델에서 사용되는 속성 정의)
      {
        'User': {
          type: 'object',
          properties: {
            id: {
              type: 'string'
            },
            age: {
              type: 'integer'
            },
            addr: {
              type: 'string'
            }
          }
        }
      }
  },
  apis: ['./routes/**/*.js'] // api 파일 위치들 
};

api 주소
각 라우터에 대한 정보를 적어주어야 swagger-ui에서 정의된대로 나온다.

/**
 * @swagger
 * tags:
 *   name: User
 *   description: 사용자 정보 가져오기
 */
module.exports = router;
 
/**
 * @swagger
 * /user/:
 *   get:
 *     summary: 사용자 정보 가져오기
 *     tags: [User]
 *     parameters:
 *       - in: query
 *         name: id
 *         type: string
 *         enum: [cjung, gglee, etc..]
 *         description: |
 *          사용자 아이디 전달
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         $ref: '#/components/res/Forbidden'
 *       404:
 *         $ref: '#/components/res/NotFound'
 *       500:
 *         $ref: '#/components/res/BadRequest'
 */
router.get('/', async (req, res, next) => {
  const {id} = req.query;
  let data = await userService.findUser(new UserDto.ParamBuilder(id).build());
 
  if (data) {
    res.json(data);
  } else {
    return next(new NotFoundError('잘못된 요청입니다.'));
  }
});

app.js
app.js에 Definition을 정의하고 swaggerSpec이랑 swaggerUI관련 설정을 해주면된다.

const swaggerJSDoc = require('swagger-jsdoc');
const swaggerOption = require('./routes/swagger');
const swaggerSpec = swaggerJSDoc(swaggerOption);
const swaggerUi = require('swagger-ui-express');
 
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

접속
http://localhost:3000/api-docs/ 에 접속하면 접속한 화면이 나온다.

#설정한 router 정보

각 router에서 정의한 api 주소 정보가 확인된다.

또한 테스트도 진행할 수 있다. 파라미터 값을 선택하고 execute 버튼을 누르면 실제 테스트를 진행하고결과까지 보여 준다.

그리고 함께 정의하였던 response 정보도 확인할 수 있다.

마지막으로 Definion 문서 마지막에 정의하였던 각 Model의 Definition도 확인할 수 있다. 

자세한 문서는 여기 참고
https://frontalnh.github.io/2017/11/22/nodejs-swagger-api-doc-%EA%B5%AC%ED%98%84%ED%95%98%EA%B8%B0/

https://github.com/swagger-api/swagger-editor

위의 예제 코드는 github 참고
https://github.com/weduls/nodejs_test

## 참고로 swagger를 쓰지 않고 테스트에서 super-test 라이브러리를 사용해서 테스트할수도 있다. 하지만 ui가 없고 front나 다른 개발자한테 api 정보를 넘겨주고 테스트까지 가능하게 해주는 swagger가 좋은거 같다. (super-test는 하단의 링크 참고)

https://www.npmjs.com/package/supertest