Swagger(SpringDoc OpenAPI 3) 세팅!

OpenAPI 3 라이브러리 선택 이유

---

• Spring Boot 3.x부터는 Springfox가 더 이상 공식적으로 지원되지 않아서, 새로운 프로젝트에서는 SpringDoc을 사용하는 게 훨씬 유리하다고 합니다.
• 또한, SpringDoc은 의존성 추가만 하면 자동으로 문서 생성되며, Spring WebFlux도 지원합니다.

 

의존성 추가

---

(Maven 사용 시)

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

(Gradle 사용 시)

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

 

 

OpenAPI 문서 기본 경로

---

Spring Boot 애플리케이션 실행 후, API 문서는 기본적으로 다음 경로에서 확인 가능합니다.

1. JSON 형식: http://localhost:8080/v3/api-docs
2. YAML 형식: http://localhost:8080/api-docs.yaml
3. Swagger UI: http://localhost:8080/swagger-ui/index.html

경로 커스텀 하는 방법

1. application.properties에서 커스텀 할 수 있습니다.

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui

2. application.yml에서 커스텀 할 수 있습니다.

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

 

 

기본 OpenAPI 설정 추가

---

Swagger 문서에서 API 정보를 제공하려면 @OpenAPIDefinition 및 @Info 어노테이션을 사용합니다.

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

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "My API", version = "1.0", description = "Spring Boot 3.x OpenAPI 문서 예제")
)
public class SwaggerConfig {
}

 

 

컨트롤러에서 API 문서에 설명 남기는 방법

---

Swagger에서 API 문서에 표시하려면 @Operation, @Parameter, @ApiResponse 등의 어노테이션을 추가합니다.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/users")
@Tag(name = "User API", description = "사용자 관련 API")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "사용자 조회", description = "ID를 기반으로 사용자 정보를 조회")
    @ApiResponse(responseCode = "200", description = "조회 성공")
    @ApiResponse(responseCode = "404", description = "사용자 없음")
    public String getUserById(
        @Parameter(description = "사용자 ID", example = "1") @PathVariable Long id
    ) {
        return "User " + id;
    }

    @GetMapping
    @Operation(summary = "모든 사용자 조회", description = "전체 사용자 목록을 조회")
    public List<String> getAllUsers() {
        return List.of("User1", "User2", "User3");
    }
}

 

 

Swagger UI에서 JWT 토큰 인증 추가

---

해당 문서를 찾기 위해서 정말 많이 헤맸습니다..ㅠ
JWT 인증이 필요한 API의 경우, Swagger UI에서 토큰을 입력할 수 있도록 설정 가능합니다.

1. SwaggerConfig.java에 Security 설정 추가

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "My API", version = "1.0", description = "Spring Boot 3.x OpenAPI 문서 예제"),
    security = @SecurityRequirement(name = "BearerAuth")
)
@SecurityScheme(
    name = "BearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class SwaggerConfig {
}

2. 컨트롤러에 JWT 인증 적용

import io.swagger.v3.oas.annotations.security.SecurityRequirement;  
import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RequestMapping;  
import org.springframework.web.bind.annotation.RestController;

@RestController  
@RequestMapping("/secure")  
@SecurityRequirement(name = "BearerAuth")  
public class SecureController {

  @GetMapping
  public String secureEndpoint() {
      return "This is a secured endpoint";
    }
}

이후, Swagger UI를 브라우저에서 토큰 값을 넣으며 요청을 테스트 할 수 있습니다.

 

 

 

참고문서
https://www.baeldung.com/spring-rest-openapi-documentation
https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api