[Node.js] Swagger 도입하기

 

※ Swagger(스웨거)
다른 개발자와 협업하여 개발할 때 API 명세서는 필수이다. 여기에 소요되는 시간은 적지 않고 API가 수정될 때마다 문서도 함께 수정해줘야 한다는 번거로움이 있다. 
Swagger는 Open Api Specification(OAS) 를 위한 프레임워크로, API 들이 가지고 있는 스펙을 명세, 관리할 수 있는 프로젝트이다. 

개발자들에게 아주 단비같은 존재라 할까나...?⭐️

 

---

Swagger 도입하기

---

 

1. Swagger 설치하기

$ npm install -g swagger

 

2. Swagger 프로젝트 만들기

$ swagger project create swagger-test

? Framework? express

 

* swagger-edit 툴을 이용하여 API를 디자인할 수 있다.

$ swagger project edit

 

3. 프로젝트 시작하기

$ swagger project start

 

시작하는데 아주 혹시라도 아래와 같은 오류가 난다면 

Error initializing middleware
Error: Cannot find module '${PATH}/swagger-test/api/fittings/swagger_router'

당황하지 말자. 노드 버전 차이로 발생하는 오류라 한다. 아래와 같이 수정해 주자.

$ vi node_modules/bagpipes/lib/fittingTypes/user.js

### 아래 부분 수정 
# var split = err.message.split(path.sep);
var split = err.message.split('\n')[0].split(path.sep);

 

---

스웩~

---

 

+

4. 효율적인 Swagger UI 사용을 위해 swagger-tools 를 설치해줬다.

$ npm install swagger-tools

 

▷ app.js

'use strict'

const SwaggerExpress = require('swagger-express-mw')
const SwaggerTools = require('swagger-tools')
const express = require('express')
const app = express()

const config = {
  appRoot: __dirname, // required config
}

const options = {
  controllers: './api/controllers',
}

SwaggerExpress.create(config, function (err, swaggerExpress) {
  if (err) {
    throw err
  }

  // install middleware
  swaggerExpress.register(app)

  const port = process.env.PORT || 10010
  app.listen(port)

  let swaggerObjectLoaded = swaggerExpress.runner.swagger
  SwaggerTools.initializeMiddleware(swaggerObjectLoaded, function (middleware, err) {
    app.disable('etag')
    app.use(middleware.swaggerMetadata())
    app.use(middleware.swaggerValidator())
    app.use(middleware.swaggerRouter(options))

    app.use(middleware.swaggerUi())

    app.get('/', (req, res) => {
      try {
        res.status(200).redirect('/docs/#/')
      } catch (e) {
        logger.error(e)
        res.status(500).send()
      }
    })
  })
})

module.exports = app