Java 11 Spring Boot에서 Swagger 설정 및 사용 방법

Spring Boot에서 API 문서를 자동으로 생성하는 Swagger를 설정하는 방법을 단계별로 정리하였습니다. Swagger를 사용하면 API 문서를 쉽게 관리할 수 있으며, 개발자뿐만 아니라 비개발자도 API를 직관적으로 이해하고 테스트할 수 있습니다.

1. Swagger란?

Swagger는 RESTful API 문서를 자동으로 생성해주는 도구로, API의 사용 방법을 쉽게 확인하고 테스트할 수 있도록 도와줍니다. 최근에는 Swagger의 발전형인 **OpenAPI Specification (OAS)**가 표준으로 자리 잡았으며, springdoc-openapi 라이브러리를 활용하여 Spring Boot 프로젝트에 쉽게 적용할 수 있습니다.

1.1 Swagger의 주요 기능

• API 문서 자동 생성
• API 테스트 기능 제공 (Swagger UI)
• 코드와 문서의 동기화 유지
• 다양한 언어 및 프레임워크 지원

이 글에서는 최신 방식인 springdoc-openapi 라이브러리를 사용하여 Swagger를 설정하는 방법을 다룹니다.

 

2. 프로젝트에 Swagger 라이브러리 추가하기

Spring Boot 프로젝트에서 Swagger를 사용하려면 필요한 라이브러리를 추가해야 합니다.

2.1 build.gradle (Gradle 사용 시)

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

2.2 pom.xml (Maven 사용 시)

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

이 라이브러리는 OpenAPI 3.0을 기반으로 Swagger UI를 제공하며, 최신 Spring Boot 버전과 호환됩니다.

 

3. Swagger 기본 설정

Swagger를 활성화하려면 application.properties 또는 application.yml에 설정을 추가해야 합니다.

3.1 application.properties

springdoc.api-docs.enabled=true
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html

3.2 application.yml

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    path: /swagger-ui.html

이 설정을 통해 Swagger UI가 활성화되며, API 문서를 확인할 수 있는 경로가 지정됩니다.

 

4. Swagger UI 확인하기

서버를 실행한 후, 브라우저에서 아래 URL에 접속하면 Swagger UI를 확인할 수 있습니다.

http://localhost:8080/swagger-ui.html

Swagger UI에서는 API 목록을 확인하고, 직접 요청을 보내볼 수 있는 인터페이스를 제공합니다. 이를 통해 API 테스트가 용이해집니다.

 

5. 컨트롤러에 Swagger 어노테이션 추가하기

Swagger 문서에 API 정보를 명확하게 표현하기 위해 Swagger 어노테이션을 사용합니다. 컨트롤러에 적용하면 API의 개요 및 상세 정보를 문서화할 수 있습니다.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Example API", description = "Swagger 예제 API")
@RestController
public class ExampleController {

    @Operation(summary = "Hello API", description = "이 API는 간단한 Hello 메시지를 반환합니다.")
    @GetMapping("/hello")
    public String hello(@RequestParam String name) {
        return "Hello, " + name;
    }
}

이렇게 설정하면 Swagger UI에서 API의 설명이 자동으로 문서화되며, summary 및 description이 반영됩니다.

 

6. API 문서 예제 확인하기

Swagger UI에서 Example API 섹션을 찾아 Hello API 엔드포인트를 테스트할 수 있습니다.

요청 예시

GET /hello?name=John

응답 예시

{
    "message": "Hello, John"
}

Swagger UI에서 직접 요청을 보내보고 응답을 확인할 수 있습니다.

 

7. 추가 설정 및 커스터마이징

Swagger는 기본 설정 외에도 다양한 커스터마이징이 가능합니다.

7.1 Swagger UI 경로 변경

기본 /swagger-ui.html 대신 다른 경로로 변경하려면 application.yml에 다음을 추가합니다.

springdoc:
  swagger-ui:
    path: /api-docsspringdoc:
  swagger-ui:
    path: /api-docs

이제 Swagger UI는 http://localhost:8080/api-docs 에서 접근할 수 있습니다.

7.2 특정 API만 노출하기

모든 API가 Swagger에 나타나는 것이 아니라 특정 패키지의 컨트롤러만 표시되도록 설정할 수도 있습니다.

springdoc:
  packages-to-scan: com.example.api.controllers

이 설정을 적용하면 com.example.api.controllers 패키지에 속한 컨트롤러만 Swagger UI에 표시됩니다.

7.3 API 버전 정보 추가

Swagger UI에 API 버전 정보를 추가하려면 @OpenAPIDefinition 어노테이션을 사용하면 됩니다.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = "Example API", version = "1.0", description = "Swagger API 문서 예제")
)
@Configuration
public class SwaggerConfig {
}

이 설정을 적용하면 Swagger UI의 문서 제목 및 버전 정보가 표시됩니다.