Express.js는 Node.js를 위한 강력한 웹 애플리케이션 프레임워크입니다. 이번 글에서는 Express.js 프레임워크에서 Swagger를 사용하여 API 문서를 자동으로 생성하는 방법에 대해 알아보겠습니다.

Swagger란 무엇인가요?

Swagger는 OpenAPI Specification의 구현체로, API 개발 및 문서화를 위한 표준 규격입니다. Swagger를 사용하면 개발자는 API를 설계하고 문서화하기 위해 별도의 작업을 할 필요 없이, 코드와 동기화된 자동화된 문서를 생성할 수 있습니다.

Swagger-UI 설치

먼저, Express.js 프로젝트에 Swagger-UI를 설치해야 합니다. 아래 명령어를 사용하여 npm을 통해 Swagger-UI를 설치합니다.

npm install swagger-ui-express

Swagger 문서 작성

Swagger 문서는 YAML 또는 JSON 형식으로 작성할 수 있습니다. 여기에서는 YAML 형식으로 작성하는 방법을 알아보겠습니다.

swagger: "2.0"
info:
  version: "1.0.0"
  title: "Express.js API"
paths:
  /users:
    get:
      summary: "Get all users"
      responses:
        200:
          description: "OK"
  /users/{id}:
    get:
      summary: "Get a specific user"
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        200:
          description: "OK"

위의 예시는 /users 엔드포인트에서 모든 사용자를 가져오는 GET 요청과, /users/{id} 엔드포인트에서 특정 사용자를 가져오는 GET 요청을 정의하는 Swagger 문서입니다.

Express.js에서 Swagger-UI 사용

이제 Express.js 애플리케이션에서 Swagger-UI를 사용하는 방법을 알아보겠습니다.

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const app = express();

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

app.listen(3000, () => {
  console.log('Server started on port 3000');
});

위의 코드에서 swaggerDocument 변수는 앞서 작성한 Swagger 문서를 가져오는 부분입니다. app.use를 사용하여 /api-docs 엔드포인트에 Swagger-UI를 연결합니다.

실행 및 확인

Express.js 애플리케이션을 실행한 후, 브라우저에서 http://localhost:3000/api-docs로 접속하면 Swagger-UI를 통해 자동 생성된 API 문서를 볼 수 있습니다.

결론

이제 Express.js에서 Swagger를 사용하여 API 문서를 자동으로 생성하는 방법을 알아보았습니다. Swagger를 사용하면 개발자는 API를 구축하면서 동시에 문서화를 할 수 있으며, 이를 통해 API의 이해도와 유지 보수성을 크게 향상시킬 수 있습니다.

더 자세한 내용은 Swagger 공식 문서를 참고하시기 바랍니다.