[JAVA] Swagger / OpenAPI로 API 문서 자동화 – 실무 중심 적용 가이드

RESTful API를 개발한 뒤, 이를 클라이언트나 프론트엔드 개발자에게 공유하기 위해서는 명확한 API 문서화가 필요합니다. Spring Boot에서는 Swagger (현재는 OpenAPI)를 사용해 자동화된 API 문서를 손쉽게 생성할 수 있습니다.

 

 

1. Swagger와 OpenAPI란?

Swagger는 API 명세를 작성하고 시각화하며 테스트까지 가능한 오픈소스 프레임워크입니다. 현재는 OpenAPI Specification(OAS)이라는 이름으로 발전되었으며, Swagger는 OpenAPI의 구현체 중 하나입니다.

• OpenAPI: API 명세의 표준 스펙
• Swagger UI: 명세 기반 문서화 및 테스트 웹 UI
• Swagger Codegen: 클라이언트/서버 코드 자동 생성

 

2. Spring Boot에서 Swagger 적용 방법

2.1 의존성 추가 (Spring Boot 3.x 기준)

Spring Boot 3 이상에서는 springdoc-openapi가 Swagger의 사실상 표준 구현체로 사용됩니다.

// build.gradle
dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}

2.2 기본 접속 경로

설정만 하면 별도 코드 없이도 자동으로 API 문서가 생성되며, 아래 경로에서 확인할 수 있습니다.

• Swagger UI: /swagger-ui/index.html
• OpenAPI JSON: /v3/api-docs

2.3 기본 API 문서 커스터마이징

@OpenAPIDefinition(
    info = @Info(
        title = "My Project API",
        description = "백엔드 REST API 명세서",
        version = "v1.0"
    ),
    servers = @Server(url = "https://api.example.com", description = "운영 서버")
)
@Configuration
public class OpenApiConfig {}

 

3. 주요 어노테이션 정리

Swagger 문서의 가독성을 높이기 위해 Controller, DTO, Response 클래스에 메타 정보를 추가할 수 있습니다.

어노테이션	설명
@Operation	각 API 메서드에 대한 설명
@Parameter	요청 파라미터에 대한 설명
@RequestBody	요청 본문 내용 정의
@ApiResponse	응답 상태 코드 및 설명 정의
@Schema	DTO 필드 설명 (타입, 필수 여부 등)

예시: 컨트롤러 메서드에 적용

@Operation(summary = "회원 조회", description = "ID로 회원 정보를 조회합니다")
@GetMapping("/users/{id}")
public UserDto getUser(
    @Parameter(description = "회원 ID", example = "1") @PathVariable Long id
) {
    return userService.findById(id);
}

예시: DTO 필드 설명 추가

public class UserDto {

    @Schema(description = "회원 ID", example = "1")
    private Long id;

    @Schema(description = "회원 이름", example = "홍길동")
    private String name;
}

 

4. 실전 적용 팁

• Swagger 문서는 API 계약서이다. – 팀 간 협업 시 문서 기준이 되므로 설명을 충실히 작성하는 것이 중요함
• 운영 환경에서는 Swagger UI를 막자. – 보안상 Swagger는 운영에 노출하지 말고 dev/stage에서만 활성화하는 것이 일반적
• API Response를 DTO로 명확히 분리 – 명확한 스펙을 위해 Entity → Response DTO 변환 필수

 

5. 설정 예시: 운영 환경 Swagger 비활성화

# application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

 

결론

Swagger/OpenAPI를 활용하면 API 명세 작성, 테스트, 클라이언트 공유까지 자동화할 수 있습니다. 문서화는 단순한 개발자의 업무가 아니라 서비스의 신뢰도와 유지보수성을 높이는 중요한 작업입니다.

Swagger 적용은 어렵지 않지만, 어노테이션 작성 습관화와 DTO의 설계 품질이 API 문서 품질을 좌우합니다. Spring Boot + OpenAPI 기반으로 문서화를 체계화해두면 프로젝트 관리가 훨씬 수월해집니다.