[NodeJS] API 문서 툴 Swagger 사용해서 API 문서 자동화 (+ swagger-autogen)

 

 

회사를 다니면서 프론트와 백엔드가 협업하기 위해서 가장 필요한 요소가 API 문서라는 것을 알았습니다.

클라이언트-서버 간의 통신을 정리하는 것이 API 문서입니다.

근데 이걸 아주 조금이라도 잘못 쓰거나 누락시키면 큰일이 됩니다.

그렇기 때문에 API 문서를 작성해주는 툴들이 존재하고 그중에서 가장 유명한 Swagger입니다.

 

Swagger를 찾아보니 일일이 주석을 작성해야해서 굳이 이걸 써야 하는가에 대해 고민했습니다.

귀찮은 것을 싫어하는 개발자답게 좀 더 찾아보니 swagger를 자동 생성해주는 라이브러리가 있더라고요!

swagger-autogen을 이용해서 한 번 API 문서를 자동으로 만들어보도록 하죠.

 

 

 

1. 서버(nodemon 포함)를 멈추고 라이브러리 설치 - 매우 중요 ⭐️⭐️⭐️⭐️⭐️ 

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

서버를 끈 상태에서 swagger-ui-express와 swagger-autogen 라이브러리를 설치해줍니다.

 

서버를 멈추는 이유는 이 자동 생성 라이브러리가 동작하는 이유와 관련이 있습니다.

작동하는 원리가 작성한 swagger.js를 통해 설정한 파일들의 라우터를 읽어옵니다.

그런 다음 자동으로 swagger-output.json이라는 파일을 생성되더라고요!

생성된 json 파일을 바탕으로 swagger 문서가 생성되는데 서버를 안 멈춘 상태로 코드를 작성하면 파일 생성이 되지 않습니다 😅 

제가 swagger-output.json이 파일이 자동으로 생성된다는 것을 몰라서.. 많이 헤맸어요 하하하

 

 

2. swagger.js 파일 작성

// swagger.js
const swaggerAutogen = require('swagger-autogen')();

const options = {
  info: {
    title: 'TEST API Docs',
    description: 'test api 문서입니다',
  },
  servers: [
    {
      url: 'http://localhost:3000',
    },
  ],
  schemes: ['http'],
  securityDefinitions: {
    bearerAuth: {
      type: 'http',
      scheme: 'bearer',
      in: 'header',
      bearerFormat: 'JWT',
    },
  },
};

const outputFile = './common/swagger-output.json';
const endpointsFiles = ['./app.ts'];
swaggerAutogen(outputFile, endpointsFiles, options);

여기에서 가장 신경써주어야 하는 것은 바로 endpointsFiles입니다!

endpointsFiles의 경로는 최상단 router가 있는 곳인데요.

대부분 router을 나누셨다면 app.ts(혹은 app.js)가 될 것입니다.

 

 

 

3. swagger-output.json 파일 생성하기 - 매우 중요 ⭐️⭐️⭐️⭐️⭐️ 

잘은 모르겠지만 swagger-output.json 파일이 다른 분들 글에서는 서버 키면 자동 생성되는 것 같은데..

저 같은 경우에는 자동 생성이 되지 않더라고요 😭   

다행히도 라이브러리 공식문서에 해당 내용이 있어 파일을 생성할 수 있었습니다.

저처럼 json 파일이 생성되지 않는 분들은 우선 package.json 파일에 가셔서 

 

// package.json
"scripts": {
        // ... ,
        "swagger-autogen": "node ./swagger.js"
    }

scripts에 저 한 줄을 추가해주시면 됩니다.

 

npm run swagger-autogen

그런 다음 npm으로 swagger-autogen을 실행시켜주세요.

 

이렇게 나오셨으면 json 파일이 생성된 것입니다!

swagger.js 파일에 outputFile에 설정한 경로에 가시면 swagger-output.json 파일이 있습니다.

 

 

4. swagger  API 연결해주기

인제 잘 생성된 swagger-output.json 파일을 swagger에 연결해주면 끝입니다!

app.ts로 가셔서

const swaggerUi = require('swagger-ui-express');
const swaggerFile = require('./common/swagger-output.json')

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerFile, { explorer: true }));

이렇게 API를 만들어 연결해주시면 됩니다.

인제 서버를 키신 다음 해당 경로(api-docs)로 가셔서 확인하시면 잘 된 것을 확인할 수 있습니다.

 

제가 만든 API들이 잘 나왔습니다 👏👏👏

저 페이지가 잘 나오자마자 눈물이..

위에 json 파일 생성 때문에 어제부터 고생했더니 흑흑

 

 

반응형

 

5. 다듬기

잘 나와서 기쁘지만 너무 지저분해서 다듬어주어야 할 것 같네요.

우선 tag를 통해서 그룹화를 해야할 것 같습니다.

app.get('/path', (req, res) => {
        ...
        // #swagger.tags = ['Users']
        ...
    })

공식문서를 보니 API 함수 내부에 작성해주더라고요.

주석이 보기 싫으신 분들은 swagger-output.json에 가셔서 일일이 추가하셔도 됩니다.

저는 그게 비효율적이라고 생각해서 함수 내부에 작성했어요.

 

 

/**
    * #swagger.tags = ['test']
    * #swagger.summary = 'test'
    * #swagger.description = 'test'
    */

이렇게 적어주시면 명세서에 반영이 됩니다!

저는 자동으로 반영이 안되서 다시 json 파일 업로드 해주고 서버를 켰습니다.

 

문서 한 번씩 보시고 필요한 내용은 직접 채워넣을 수 밖에 없습니다.

공식 문서를 한 번 보시면 더욱 아실 수 있어요.

공식 문서 : https://github.com/davibaltar/swagger-autogen#readme

GitHub - davibaltar/swagger-autogen: This module performs the automatic construction of the Swagger documentation. The module ca

 

 

 

+ 번외

사용하면서 해결해야할 점이 두가지가 있더라고요.

 

1. 내용 변경시 자동으로 json 업데이트

2. 프론트에 공유할 방법

 

좀 더 알아보고 내용 업데이트 하도록 하겠습니다~