🚀 Spring Boot 3 + Swagger(OpenAPI 3) 적용 가이드

📝 개요

백엔드 API를 개발하다 보면 프론트엔드/QA 팀과 API 명세를 문서로 공유하는 일이 필수적입니다.
과거에는 Excel이나 Wiki에 수동으로 작성했지만, 이제는 Swagger(OpenAPI) 를 통해 API 문서를 자동으로 생성하고 유지보수할 수 있습니다.

이번 글에서는 Spring Boot 3.4 + Java 21 + Gradle 환경을 기준으로, Swagger를 적용하고 운영할 때의 Best Practice를 소개합니다.

🔧 1. 의존성 추가

build.gradle에 OpenAPI 관련 의존성을 추가합니다.
Spring Boot 3에서는 springdoc-openapi 라이브러리가 가장 많이 사용됩니다.

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
}

📌 2. Swagger UI 접근 방법

의존성만 추가하면 자동으로 Swagger UI 가 활성화됩니다.

기본 경로: http://{{호스트}}:{{포트}}/swagger-ui.html

OpenAPI 문서(JSON): http://{{호스트}}:{{포트}}/v1/api-docs

회사 내 보안 정책에 따라 접근 권한을 제어하거나, 프로필별로 설정을 분리하는 것이 중요합니다.

⚙️ 3. Swagger 설정 커스터마이징

/**
 * Swagger UI 상단에 표시되는 API 정보가 이 부분에서 설정
 */
@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "테스트 전용 API",
                description = "개인적으로 테스트하기 위한 API 문서입니다",
                version = "v1"
        )
)
public class SwaggerConfiguration {

}



/**
 * Swagger 화면에서 사용자 편의성을 높이는 옵션
 * Swagger UI에서 사용자/관리자 API를 탭으로 구분
 */

springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  api-docs:
    path: /v1/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: alpha
    tags-sorter: alpha
    display-query-params-without-oauth2: true
    disable-swagger-default-url: true
    doc-expansion: list
    defaultModelsExpandDepth: 1
    defaultModelExpandDepth: 2
    defaultModelRendering: model
    show-extensions: true
    show-common-extensions: true
    display-request-duration: true
    try-it-out-enabled: true
  group-configs:
    - group: 사용자
      paths-to-match:
        - /v1/member/**
        - /v1/board/**
    - group: 관리자
      paths-to-match:
        - /v1/admin/**

🛠 4. Controller 예제

/**
 * 사용자 생성 API
 */
    @Operation(
            summary = "사용자 생성",
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    required = true,
                    content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = CreateMemberRequest.class)
                    )
            ),
            responses = {
                    @ApiResponse(
                            responseCode = "201",
                            description = "사용자 생성 완료",
                            content = {
                                    @Content(
                                            mediaType = "application/json",
                                            schema = @Schema(implementation = CommonResponse.class)
                                    ),
                            }
                    ),
            }
    )
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public CommonResponse createMember(@Valid @RequestBody CreateMemberRequest createMemberRequest) {
        Member member = memberWebMapper.toDomain(createMemberRequest);
        Member resultMember = createMemberUseCase.createMember(member);
        CreateMemberResponse createMemberResponse = memberWebMapper.toCreateMemberResponse(resultMember);
        CommonResponse commonResponse = new CommonResponse<>("사용자 생성이 정상적으로 처리됐습니다", createMemberResponse);
        return commonResponse;
    }

👉 5. 활용 사례

• 백엔드(Spring Boot) → /v1/api-docs 제공
• 프론트엔드 → OpenAPI Generator, orval, swagger-typescript-api 등을 활용하여
  • 타입 정의
  • API 호출 코드
  • React Query/SWR 훅 자동으로 생성 가능

🎯 6. 마무리

Swagger(OpenAPI)는 API 개발/운영에서 협업 효율을 극대화하는 도구입니다.
Spring Boot에서는 springdoc-openapi를 통해 쉽게 적용할 수 있고,
보안/프로필 분리/문서 관리까지 신경쓴다면 실무에 바로 적용 가능한 베스트 프랙티스가 됩니다.