Node.js Express 환경에서 Swagger와 Redoc을 활용한 API 문서화

Node.js와 Express.js를 사용하여 API를 개발할 때, API 문서화는 필수적인 작업입니다. 잘 정돈된 API 문서는 개발자들 간의 효율적인 협업을 돕고, API를 사용하는 클라이언트 개발자들에게 명확한 가이드를 제공합니다. 이 글에서는 Swagger와 Redoc 라이브러리를 활용하여 Node.js Express 환경에서 API 문서를 자동 생성하는 방법을 상세히 알아보겠습니다.

 

728x90

Swagger란 무엇인가?

Swagger는 RESTful API를 위한 인터페이스 설명 언어(OpenAPI Specification)를 기반으로 API를 설계하고 문서화하는 오픈 소스 프레임워크입니다. Swagger를 사용하면 API의 구조, 요청/응답 데이터 형식, 인증 방법 등을 명확하게 정의할 수 있으며, 이를 기반으로 상호 작용 가능한 API 문서를 생성할 수 있습니다.

Redoc란 무엇인가?

Redoc은 Swagger UI와 함께 사용되는 또 다른 OpenAPI 스펙을 위한 UI 라이브러리입니다. Swagger UI보다 더 현대적이고 사용자 친화적인 인터페이스를 제공하며, 다양한 커스터마이징 옵션을 지원합니다.

Node.js Express 환경에서 Swagger와 Redoc 설정하기

1. 프로젝트 설정:
   • Node.js와 npm(또는 yarn)이 설치되어 있어야 합니다.
   • 새로운 Node.js 프로젝트를 생성하고 npm을 통해 필요한 패키지를 설치합니다.
   • npm install express swagger-jsdoc swagger-ui-express
2. Swagger 설정 파일 생성:
   • swagger.yaml 또는 swagger.json 파일을 생성하고 API 정보를 정의합니다.
      

     openapi: 3.0.0
     info:
       title: My API
       version: 1.0.0
       description: A sample API
     servers:
       - url: http://localhost:3000
     paths:
       /users:
         get:
           summary: Returns a list of users
           responses:
             200:
               description: A list of users
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       $ref: '#/components/schemas/User'
     components:
       schemas:
         User:
           type: object
           properties:
             id:
               type: integer
             name:
               type: string
     

    
3. Express 서버에서 Swagger UI 설정:
   JavaScript

    

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocument = require('./swagger.json');
   
   const app = express();
   
   // ... (기존 Express 설정)
   
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
   
   app.listen(3000, () => {
       console.log('Server listening on port 3000');
   });
   

4. Redoc 설정 (선택 사항):
   • npm install redoc-cli
   • redoc-cli bundle -o docs/index.html 명령을 실행하여 HTML 파일을 생성합니다.
   • 생성된 HTML 파일을 서버에서 제공합니다.

Swagger UI 사용하기

브라우저에서 http://localhost:3000/api-docs로 접속하면 Swagger UI가 실행되고, 정의된 API 목록과 상세 정보를 확인할 수 있습니다.

Swagger의 장점

• 자동 문서 생성: 코드 기반으로 API 문서를 자동 생성하여 개발 생산성 향상
• 시각적 인터페이스: 사용자 친화적인 인터페이스를 통해 API를 쉽게 탐색하고 테스트 가능
• 다양한 도구 지원: Swagger UI 외에도 다양한 도구와 통합하여 API 개발 및 관리를 효율적으로 수행
• OpenAPI 표준 준수: OpenAPI Specification을 준수하여 확장성과 호환성이 높음

Redoc의 장점

• 현대적이고 사용자 친화적인 인터페이스: Swagger UI보다 더 세련되고 보기 좋은 인터페이스 제공
• 커스터마이징: 다양한 테마와 설정을 통해 문서를 커스터마이징 가능
• 빠른 렌더링: 빠른 렌더링 속도로 사용자 경험을 향상

결론

Swagger와 Redoc을 활용하면 Node.js Express로 개발한 API를 효과적으로 문서화하고, 개발팀과 다른 개발자들과 쉽게 공유할 수 있습니다. 이를 통해 API 개발 생산성을 높이고, API의 품질을 향상시킬 수 있습니다.

 

728x90

이 코드는 Node.js 환경에서 Express.js를 사용하여 API를 문서화하는 방법을 보여줍니다. Swagger와 Redoc 라이브러리를 활용하여 OpenAPI 사양에 기반한 API 문서를 생성합니다. 먼저 필요한 패키지를 설치한 후, Express 서버를 설정하고 OpenAPI 사양을 정의합니다. `/api-docs` 경로에서 Swagger UI를 통해 API 문서를 시각적으로 확인할 수 있으며, `/redoc` 경로에서는 Redoc을 통해 문서를 제공합니다. 

개선점으로는 API 라우트 파일을 분리하여 관리하면 코드의 가독성과 유지보수성을 높일 수 있습니다. 또한, 에러 핸들링을 추가하여 API의 안정성을 강화하는 것도 좋은 방법입니다. 마지막으로, 실제 API의 다양한 엔드포인트를 추가하여 문서화의 유용성을 극대화할 수 있습니다.

// 1. 필요한 패키지 설치
// npm install express swagger-jsdoc swagger-ui-express redoc-express

// 2. 필요한 모듈 임포트
const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const redoc = require('redoc-express');

const app = express();
const port = 3000;

// 3. OpenAPI 사양 정의
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Sample API',
      version: '1.0.0',
      description: 'A sample API for demonstration',
    },
  },
  apis: ['./routes/*.js'], // API 라우트 파일 위치
};

const openapiSpecification = swaggerJsdoc(options);

// 4. Swagger UI 설정
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openapiSpecification));

// 5. Redoc 설정
app.use('/redoc', redoc({
  title: 'API Documentation',
  specUrl: '/swagger.json',
  redocOptions: {
    theme: {
      colors: {
        primary: {
          main: '#6EC5AB'
        }
      }
    }
  }
}));

// OpenAPI 사양 JSON 제공
app.get('/swagger.json', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(openapiSpecification);
});

// 샘플 API 라우트
/**
 * @openapi
 * /api/hello:
 *   get:
 *     summary: Returns a hello message
 *     responses:
 *       200:
 *         description: Hello World!
 */
app.get('/api/hello', (req, res) => {
  res.json({ message: 'Hello World!' });
});

// 서버 시작
app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
  console.log(`Swagger UI available at http://localhost:${port}/api-docs`);
  console.log(`Redoc available at http://localhost:${port}/redoc`);
});