API 문서화 (Swagger)

1. 도입 (왜 배워야 하는가)

API 문서화는 소프트웨어 개발에서 매우 중요한 과정입니다. 특히, 여러 팀이 협업하는 대규모 프로젝트에서는 API의 명확한 문서화가 필수적입니다. Swagger는 RESTful API를 문서화하고 테스트하는 데 사용되는 도구로, 개발자와 비개발자 간의 원활한 소통을 돕습니다. 이를 통해 API의 사용법을 이해하고, 이를 기반으로 한 서비스 개발이 더욱 원활해집니다.

만약 API 문서화가 제대로 이루어지지 않는다면, 개발자들이 API를 어떻게 사용할지에 대한 혼란이 생길 수 있으며, 잘못된 사용으로 인한 버그나 서비스 장애가 발생할 수 있습니다. 따라서, API 문서화는 소프트웨어 품질을 높이고, 유지보수 비용을 줄이는 데 큰 기여를 합니다.

2. 핵심 개념 설명

Swagger는 API 문서화와 테스트를 위한 오픈 소스 도구입니다. Swagger를 사용하면 API의 구조를 정의하고, 이를 기반으로 자동으로 문서를 생성할 수 있습니다. 여기서는 Swagger의 두 가지 주요 개념을 설명합니다.

Swagger UI는 마치 레스토랑의 메뉴판처럼, API의 사용법을 시각적으로 제공합니다. OpenAPI는 메뉴의 레시피와 같아서, 메뉴판을 만들기 위해 필요한 모든 정보를 담고 있는 형식입니다.

3. 기본 코드 예제

Swagger를 설정하기 위한 기본적인 코드 예제를 살펴보겠습니다.

const express = require('express');
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();

// Swagger 설정
const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'API 문서화 예제',
      version: '1.0.0',
      description: 'API 문서화 예제를 위한 Swagger 설정',
    },
  },
  apis: ['./routes/*.js'], // API 문서화할 파일 경로
};

// Swagger 문서 생성
const swaggerDocs = swaggerJsDoc(swaggerOptions);

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

// 서버 시작
app.listen(3000, () => {
  console.log('서버가 3000번 포트에서 실행 중입니다.');
});

실행 결과: 서버가 성공적으로 실행되면 http://localhost:3000/api-docs에서 Swagger UI를 통해 API 문서를 볼 수 있습니다.

• const express = require('express');: Express.js 모듈을 불러옵니다.
• const swaggerJsDoc = require('swagger-jsdoc');: Swagger 문서를 생성할 모듈을 불러옵니다.
• const swaggerUi = require('swagger-ui-express');: Swagger UI를 사용할 수 있게 해주는 모듈을 불러옵니다.
• const swaggerOptions = { ... };: Swagger 문서의 기본 정보를 설정합니다.
• const swaggerDocs = swaggerJsDoc(swaggerOptions);: Swagger 설정에 따라 문서를 생성합니다.
• app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));: Swagger UI를 설정합니다.
• app.listen(3000, () => { ... });: 서버를 3000번 포트에서 실행합니다.

4. 실전 활용 예제

예제 1: 사용자 등록 API

쇼핑몰에서 사용자가 회원가입을 할 때 필요한 API를 문서화하는 경우입니다.

/*
  @swagger
  /register:
    post:
      summary: 사용자 등록
      description: 새로운 사용자를 등록합니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        200:
          description: 성공적으로 등록되었습니다.
        400:
          description: 잘못된 요청입니다.
 */

예제 2: 상품 조회 API

쇼핑몰에서 특정 상품의 정보를 조회하는 API를 문서화하는 경우입니다.

/*
  @swagger
  /product/{id}:
    get:
      summary: 상품 조회
      description: ID에 해당하는 상품 정보를 조회합니다.
      parameters:
        - in: path
          name: id
          required: true
          description: 조회할 상품의 ID
          schema:
            type: integer
      responses:
        200:
          description: 상품 정보
        404:
          description: 상품을 찾을 수 없습니다.
 */

5. 흔한 실수와 주의사항

실수 1: Swagger 주석을 잘못 작성하기

잘못된 예:

/*
  @swagger
  /user:
    get:
      summary: 사용자 정보
      description: 사용자 정보를 가져옵니다
      responses:
        200:
          description: 성공적으로 가져왔습니다.
 /

올바른 예:

/*
  @swagger
  /user:
    get:
      summary: 사용자 정보
      description: 사용자 정보를 가져옵니다.
      responses:
        200:
          description: 성공적으로 가져왔습니다.
 /

주석 끝에 마침표를 추가하는 것이 좋습니다.

실수 2: API 경로를 잘못 설정하기

잘못된 예:

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

올바른 예:

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

API 경로를 정확히 설정해야 합니다.

6. 정리

• Swagger는 API 문서화와 테스트를 위한 필수 도구입니다.
• Swagger UI는 API를 시각적으로 탐색할 수 있게 도와줍니다.
• OpenAPI는 API 구조를 정의하는 형식입니다.
• API 문서화는 팀 간의 원활한 소통을 위한 필수 과정입니다.
• 주석 작성 시 주의가 필요하며, 정확한 API 경로 설정이 중요합니다.

다음에 학습하면 좋은 주제:

• RESTful API 설계 원칙
• GraphQL과 REST의 차이점
• API 버전 관리 방법