Spring Boot + Swagger

Spring Boot 3.x + Swagger 3.x

Spring Boot 3.x.. 버전에 Swagger 3.x.. 버전을 적용하기 위해 springdoc-openapi 라이브러리를 사용한다.

1. 의존성 추가

먼저 build.gradle에

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

를 추가한다.

이 의존성만 추가해도 작동은 한다.

2. OpenAPI 커스터마이징

OpenAPI의 세부 사항을 커스터마이징하기 위해 OpenAPI 빈을 설정할 수 있다.
예를 들어, API 문서의 정보를 추가하는 방법은 다음과 같다.

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                    .title("Sample API")
                    .version("1.0")
                    .description("Sample API with SpringDoc OpenAPI 3"));
    }
}

로그인 인증과 같은 Security 관련 설정도 추가할 수 있다.

3. Controller에 Annotation 추가

어노테이션을 관리하는 인터페이스를 작성해서 관리할 수 있다.

@Tag(name = "Board", description = "게시판 관련 API")
public interface BoardApi {

	@Operation(
			summary = "게시판 게시물 리스트",
			description = "커서 기반 페이지네이션 10개씩 전송"
	)
	@ApiResponse(
			responseCode = "200",
			description = "게시물 리스트 조회 성공"
	)
	@GetMapping("")
	public ResponseEntity<?> getBoards( ... );
}

1. @Tag(name = "Board", description = "게시판 관련 API")
   이 어노테이션은 API 문서에서 이 인터페이스에 정의된 메서드들을 "Board"라는 카테고리(태그) 아래에 그룹화한다.
   "게시판 관련 API"라는 설명과 함께 이 API가 게시판 관련 기능을 다룬다는 것을 표시한다.

2. @Operation(summary = "게시판 게시물 리스트", description = "커서 기반 페이지네이션 10개씩 전송")
   이 어노테이션은 특정 API 작업에 대한 요약과 설명을 제공한다.
   "게시판 게시물 리스트"라는 요약과, "커서 기반 페이지네이션을 통해 10개씩 게시물을 전송한다"는 설명을 통해 API의 기능과 작동 방식을 설명한다.

3. @ApiResponse(responseCode = "200", description = "게시물 리스트 조회 성공")
   이 어노테이션은 API 요청이 성공했을 때의 응답을 설명한다.
   "200" 응답 코드와 함께 "게시물 리스트 조회 성공"이라는 설명을 제공하여, 이 API 메서드가 성공적으로 응답할 경우의 결과를 문서화한다.

그리고 컨트롤러에서 이 인터페이스를 implements 해서 사용한다.

public class BoardController implements BoardApi { ... }

4. yml 파일에 설정 추가

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

1. api-docs

• springdoc.api-docs.path: /api-docs
  이 설정은 OpenAPI 3 스펙을 제공하는 API 문서의 경로를 설정한다.
  즉, 애플리케이션의 API 스펙이 JSON 형식으로 제공되는 경로를 /api-docs로 지정한다.
  디폴트 경로는 /v3/api-docs 이다.

2. swagger-ui

• springdoc.swagger-ui.path: /goodplassu-server
  이 설정은 Swagger UI 페이지에 접근할 수 있는 경로를 설정한다.
  사용자가 웹 브라우저를 통해 이 경로로 접속하면, 설정된 API 문서를 기반으로 한 Swagger UI를 볼 수 있다.
  기본적으로 Swagger UI의 경로는 /swagger-ui/index.html 이다.