TL;DR

1. 개념

``` Swagger = API 문서화 + 테스트 도구 (현재 OpenAPI) └── 이름 유래: “swagger” = 뽐내다, 자신있게 걷다 └── API를 “뽐내듯이” 보여준다는 의미

2. 배경

API 문서화의 고통:

3. 이유

이 주제를 이해하고 적용해야 하는 이유를 정리한다.

4. 특징

5. 상세 내용

작성일: 2026-01-28 카테고리: Backend / Development Tools 포함 내용: Swagger(OpenAPI), H2 Database, 개발 환경 설정

1. 개요

약자/이름

Swagger = API 문서화 + 테스트 도구 (현재 OpenAPI)
          └── 이름 유래: "swagger" = 뽐내다, 자신있게 걷다
          └── API를 "뽐내듯이" 보여준다는 의미

H2      = 자바 기반 인메모리 데이터베이스
          └── 이름 유래: 수소(Hydrogen)의 화학 기호
          └── 가볍고 빠르다는 의미

둘의 관계

직접적인 연관은 없음!

하지만 Spring Boot 개발 시 "로컬 개발 환경 3종 세트"로 자주 함께 사용:

┌─────────────────────────────────────────────────────────────┐
│  Spring Boot 로컬 개발 환경                                  │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Swagger   │  │     H2      │  │ Spring Boot │        │
│  │  (API 문서)  │  │ (가벼운 DB) │  │ DevTools    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│        │                │                │                 │
│        └────────────────┼────────────────┘                 │
│                         ▼                                  │
│              로컬에서 빠르게 개발/테스트                     │
└─────────────────────────────────────────────────────────────┘

프로덕션에서는:
- Swagger → 비활성화 또는 인증 추가
- H2 → MySQL, PostgreSQL 등으로 교체

2. Swagger (OpenAPI) 상세

역사적 배경

API 문서화의 고통:

옛날 방식:
├── Word/Wiki에 API 명세 작성
├── 코드 변경 → 문서 수동 업데이트 (자주 잊음)
├── 문서 ≠ 실제 코드 (싱크 안 맞음)
└── API 테스트하려면 Postman/curl 따로 사용

2011: Swagger 등장
      "코드에서 API 문서 자동 생성하자!"

2015: OpenAPI Initiative 설립
      Swagger 스펙 → OpenAPI Specification으로 표준화
      (Linux Foundation 산하)

현재:
├── OpenAPI = 스펙/표준 (3.0, 3.1)
├── Swagger = 도구 이름 (Swagger UI, Swagger Editor)
└── Springdoc/Springfox = Spring 연동 라이브러리

Swagger가 하는 일

1. API 문서 자동 생성
   코드의 어노테이션 → HTML 문서

2. API 테스트 UI 제공
   브라우저에서 바로 API 호출 가능

3. API 스펙 정의 (OpenAPI JSON/YAML)
   다른 도구와 연동 가능 (코드 생성 등)

Swagger UI 화면

┌─────────────────────────────────────────────────────────────┐
│  http://localhost:8080/swagger-ui.html                      │
│─────────────────────────────────────────────────────────────│
│                                                             │
│  My API                                                     │
│  ═══════════════════════════════════════════════            │
│                                                             │
│  ▼ User Controller                                          │
│    ┌─────────────────────────────────────────────┐         │
│    │ GET  /api/users        사용자 목록 조회     │         │
│    │ POST /api/users        사용자 생성          │         │
│    │ GET  /api/users/{id}   사용자 상세 조회     │         │
│    │ PUT  /api/users/{id}   사용자 수정          │         │
│    │ DELETE /api/users/{id} 사용자 삭제          │         │
│    └─────────────────────────────────────────────┘         │
│                                                             │
│  [Try it out] 버튼으로 바로 API 테스트 가능!                │
└─────────────────────────────────────────────────────────────┘

Spring Boot 설정

의존성 추가

// build.gradle.kts

// Springdoc OpenAPI (권장, 최신)
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0")

// 또는 Springfox (레거시, 유지보수만)
// implementation("io.springfox:springfox-boot-starter:3.0.0")

기본 설정

# application.yml
springdoc:
  api-docs:
    path: /api-docs           # OpenAPI JSON 경로
  swagger-ui:
    path: /swagger-ui.html    # Swagger UI 경로
    tags-sorter: alpha        # 태그 알파벳 정렬
    operations-sorter: alpha  # API 알파벳 정렬

컨트롤러 어노테이션

@RestController
@RequestMapping("/api/users")
@Tag(name = "User", description = "사용자 관리 API")
class UserController(
    private val userService: UserService
) {
    @Operation(
        summary = "사용자 목록 조회",
        description = "등록된 모든 사용자를 조회합니다"
    )
    @ApiResponses(
        ApiResponse(responseCode = "200", description = "성공"),
        ApiResponse(responseCode = "401", description = "인증 실패")
    )
    @GetMapping
    fun getUsers(): List<UserResponse> {
        return userService.findAll()
    }

    @Operation(summary = "사용자 생성")
    @PostMapping
    fun createUser(
        @Parameter(description = "생성할 사용자 정보")
        @RequestBody request: CreateUserRequest
    ): UserResponse {
        return userService.create(request)
    }

    @Operation(summary = "사용자 상세 조회")
    @GetMapping("/{id}")
    fun getUser(
        @Parameter(description = "사용자 ID", example = "1")
        @PathVariable id: Long
    ): UserResponse {
        return userService.findById(id)
    }
}

DTO 문서화

@Schema(description = "사용자 생성 요청")
data class CreateUserRequest(
    @Schema(description = "사용자 이름", example = "홍길동")
    val name: String,

    @Schema(description = "이메일", example = "hong@example.com")
    val email: String,

    @Schema(description = "나이", minimum = "0", maximum = "150")
    val age: Int
)

주요 어노테이션

어노테이션 용도 위치
@Tag 컨트롤러 그룹 이름 클래스
@Operation API 설명 메서드
@Parameter 파라미터 설명 파라미터
@Schema 모델/필드 설명 DTO 클래스/필드
@ApiResponse 응답 설명 메서드
@Hidden 문서에서 숨김 클래스/메서드

프로덕션 보안 설정

// 프로덕션에서 Swagger 비활성화
@Profile("!prod")  // prod 프로필이 아닐 때만 활성화
@Configuration
class SwaggerConfig {
    @Bean
    fun openAPI(): OpenAPI {
        return OpenAPI()
            .info(Info()
                .title("My API")
                .version("1.0.0")
                .description("API 문서"))
    }
}

# application-prod.yml
springdoc:
  api-docs:
    enabled: false    # 프로덕션에서 비활성화
  swagger-ui:
    enabled: false

3. H2 Database 상세

역사적 배경

개발 환경 DB의 고통:

옛날 방식:
├── 로컬에 MySQL/PostgreSQL 설치
├── 개발자마다 DB 설정 다름
├── 테스트 데이터 관리 어려움
└── CI/CD에서 DB 연결 문제

H2 등장:
├── 설치 필요 없음 (JAR 하나)
├── 인메모리 모드 (앱 시작 시 생성, 종료 시 삭제)
├── 파일 모드도 지원
└── 웹 콘솔 제공 (브라우저에서 DB 조회)

H2 특징

✅ 장점:
├── 설치 불필요 (의존성 추가만으로 사용)
├── 초고속 (인메모리)
├── 웹 콘솔 제공
├── MySQL/PostgreSQL 호환 모드
└── 테스트에 최적

❌ 단점:
├── 프로덕션 부적합
├── 인메모리 = 재시작하면 데이터 사라짐
└── 실제 DB와 미묘한 차이 가능

용도:
├── 로컬 개발
├── 단위 테스트
└── 통합 테스트

동작 모드

1. 인메모리 모드 (개발/테스트용)
   jdbc:h2:mem:testdb
   └── 앱 종료 시 데이터 삭제

2. 파일 모드 (데이터 유지)
   jdbc:h2:file:./data/mydb
   └── 파일로 저장, 재시작해도 유지

3. 서버 모드 (여러 앱에서 접근)
   jdbc:h2:tcp://localhost/~/mydb
   └── 별도 H2 서버 실행 필요

Spring Boot 설정

의존성

// build.gradle.kts
runtimeOnly("com.h2database:h2")

설정

# application.yml (개발 환경)
spring:
  datasource:
    url: jdbc:h2:mem:testdb          # 인메모리 DB
    driver-class-name: org.h2.Driver
    username: sa
    password:

  h2:
    console:
      enabled: true                   # 웹 콘솔 활성화
      path: /h2-console               # 콘솔 경로
      settings:
        web-allow-others: false       # 외부 접근 차단

  jpa:
    hibernate:
      ddl-auto: create-drop           # 시작 시 생성, 종료 시 삭제
    show-sql: true                    # SQL 로그 출력

H2 Console 화면

┌─────────────────────────────────────────────────────────────┐
│  http://localhost:8080/h2-console                           │
│─────────────────────────────────────────────────────────────│
│                                                             │
│  H2 Console                                                 │
│                                                             │
│  JDBC URL: jdbc:h2:mem:testdb                              │
│  User Name: sa                                              │
│  Password: (빈칸)                                           │
│                                                             │
│  [Connect]                                                  │
│─────────────────────────────────────────────────────────────│
│                                                             │
│  접속 후:                                                   │
│  ┌─────────────────┬───────────────────────────────┐       │
│  │ Tables          │  SQL 입력창                   │       │
│  │ ├── USERS      │                               │       │
│  │ ├── ORDERS     │  SELECT * FROM users;         │       │
│  │ └── PRODUCTS   │                               │       │
│  │                 │  [Run]                        │       │
│  └─────────────────┴───────────────────────────────┘       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

4. Swagger + H2 함께 사용

전체 구조

┌─────────────────────────────────────────────────────────────┐
│                    개발 환경 워크플로우                       │
│                                                             │
│   개발자                                                     │
│     │                                                       │
│     ├──► http://localhost:8080/swagger-ui.html             │
│     │    └── API 문서 확인 + 테스트                         │
│     │                                                       │
│     ├──► http://localhost:8080/h2-console                  │
│     │    └── DB 데이터 직접 확인/수정                       │
│     │                                                       │
│     └──► IDE에서 코드 수정                                  │
│          └── Spring DevTools로 자동 재시작                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

개발 vs 프로덕션 설정

# application-dev.yml (개발)
spring:
  datasource:
    url: jdbc:h2:mem:devdb
  h2:
    console:
      enabled: true

springdoc:
  swagger-ui:
    enabled: true

---

# application-prod.yml (프로덕션)
spring:
  datasource:
    url: jdbc:postgresql://prod-db:5432/myapp
  h2:
    console:
      enabled: false          # H2 콘솔 비활성화!

springdoc:
  swagger-ui:
    enabled: false            # Swagger 비활성화!

전체 의존성

// build.gradle.kts
dependencies {
    // Spring Boot
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")

    // Swagger (API 문서)
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0")

    // H2 (개발용 DB)
    runtimeOnly("com.h2database:h2")

    // 프로덕션 DB
    runtimeOnly("org.postgresql:postgresql")

    // DevTools (자동 재시작)
    developmentOnly("org.springframework.boot:spring-boot-devtools")
}

5. 정리

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Swagger (OpenAPI)                                          │
│  ├── 역할: API 문서 자동 생성 + 테스트 UI                   │
│  ├── 접속: /swagger-ui.html                                │
│  └── 프로덕션: 비활성화 또는 인증 필요                      │
│                                                             │
│  H2 Database                                                │
│  ├── 역할: 가벼운 인메모리 DB (개발/테스트용)               │
│  ├── 접속: /h2-console                                     │
│  └── 프로덕션: 절대 사용 X (PostgreSQL 등으로 교체)         │
│                                                             │
│  둘의 관계:                                                  │
│  ├── 직접적 연관 없음                                       │
│  ├── "개발 환경 편의 도구"로 함께 자주 사용                 │
│  └── 프로덕션에서는 둘 다 비활성화                          │
│                                                             │
│  비유:                                                       │
│  Swagger = API 설명서 + 시험장                              │
│  H2 = 연습용 공책 (지우면 사라짐)                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

관련 키워드

Swagger, OpenAPI, Springdoc, API 문서, H2, 인메모리 DB, 개발 환경, Spring Boot, DevTools