자바스크립트 미들웨어를 활용한 API 문서 자동 생성하기

17 Oct 2023

javascript

소개

API 문서는 개발자들이 사용 가능한 엔드포인트, 파라미터, 요청/응답 형식 등을 이해하는데 필수적인 도구입니다. 하지만 수동으로 문서를 작성하고 관리하는 것은 번거로운 작업일 수 있습니다. 이러한 문제를 해결하기 위해 자바스크립트 미들웨어를 활용하여 API 문서를 자동으로 생성할 수 있습니다.

미들웨어

미들웨어는 요청과 응답 사이에 위치하여 일련의 작업을 처리하는 소프트웨어 컴포넌트입니다. 자바스크립트에서 가장 인기 있는 미들웨어 중 하나는 Express.js에서 사용되는 ‘swagger-jsdoc’입니다. 이 미들웨어는 JSDoc 주석으로 작성된 코드에서 API 정의를 추출하고 Swagger 형식의 문서로 변환합니다.

API 문서 자동 생성

API 문서를 자동으로 생성하는 방법은 다음과 같습니다:

Express.js 프로젝트에 ‘swagger-jsdoc’ 미들웨어를 설치합니다:
```
npm install swagger-jsdoc
```

Express 앱 설정에 미들웨어를 추가합니다:

const swaggerJsdoc = require('swagger-jsdoc');
   
const options = {
  swaggerDefinition: {
    info: {
      title: 'API 문서',
      version: '1.0.0',
      description: 'API 문서 자동 생성 예제'
    }
  },
  apis: ['./routes/*.js'] // API 코드 파일 경로 지정
};
   
const specs = swaggerJsdoc(options);
   
app.use('/api-docs', express.static('docs')); // 생성된 문서의 경로 설정
app.use('/api-docs.json', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(specs);
});

API 코드 파일에 JSDoc 주석을 추가합니다: ```javascript /**
- @swagger
- /users:
- get:
- summary: 사용자 목록 조회
- responses:
- 200:
- description: 성공적으로 조회된 사용자 목록 */
router.get(‘/users’, (req, res) => { // 사용자 목록 조회 로직 }); ```
서버를 시작하고 ‘/api-docs’ 루트로 접속하면 Swagger 형식의 API 문서가 표시됩니다.

사용 예제

다음은 ‘swagger-jsdoc’를 사용하여 API 문서를 자동으로 생성하는 예제입니다:

const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');

const app = express();

const options = {
  swaggerDefinition: {
    info: {
      title: 'API 문서',
      version: '1.0.0',
      description: 'API 문서 자동 생성 예제'
    }
  },
  apis: ['./routes/*.js'] // API 코드 파일 경로 지정
};

const specs = swaggerJsdoc(options);

app.use('/api-docs', express.static('docs')); // 생성된 문서의 경로 설정
app.use('/api-docs.json', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(specs);
});

app.listen(3000, () => {
  console.log('서버가 시작되었습니다.');
});

목차

소개

미들웨어

API 문서 자동 생성

사용 예제

참고 자료