[Spring Boot] Spring Boot 3.X 버전에 Swagger 3 버전 적용하기

Spring Boot 3.1.2 버전에 Swagger 3 버전 적용하기

Spring Boot

 

Swagger는 API의 설계, 구축, 문서화 및 사용을 위한 강력한 오픈 소스 프레임워크로, 개발자들이 RESTful 웹 서비스를 효율적으로 만들고, 문서화하고, 사용자와 소통할 수 있도록 도와준다.

Swagger 2에서 Swagger 3 (현재 OpenAPI 3로 더 널리 알려져 있음)로의 전환은 개선된 기능을 통해 더 나은 API 문서화 경험을 제공한다.
Swagger 3는 여러 호스트 지원, 강화된 보안 정의, 콜백, 링크 기능 등을 통해 API를 더욱 세밀하게 제어할 수 있게 해 준다.

 

 

 

1. 의존성 설정 (버전은 변동될 수 있음)

• org.springdoc:springdoc-openapi-ui
  
  • OpenAPI 3 사양을 위한 Spring Boot 애플리케이션용 기본 UI를 제공한다.
  • 이것을 통해 Swagger UI를 애플리케이션에 통합하고 REST API 문서를 자동으로 생성할 수 있다.
  • 최신 버전 확인은 아래 링크에서 확인하면 된다.
  • (https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui)

implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

• org.springdoc:springdoc-openapi-starter-webmvc-ui
  • Spring MVC 프로젝트에서 사용하기 위한 스타터이며, springdoc-openapi-ui의 모든 기능을 포함하면서도 Spring MVC에 특화된 추가 구성을 제공한다.

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

 

범용적인 사용을 고려할 때, springdoc-openapi-ui는 Spring WebFlux와 Spring MVC를 모두 지원하므로 더 넓은 사용 사례에 적합하다. 만약 당신이 특별한 이유 없이 Spring MVC만을 사용하고 있다면, springdoc-openapi-starter-webmvc-ui가 더 적합할 수 있다.

 

하지만, 일반적인 경우에는 springdoc-openapi-ui가 더 많은 경우에 유연하게 사용될 수 있기 때문에 이를 기본으로 사용하는 것이 좋다.

Spring Boot 프로젝트에서 REST API 문서화는 중요한 부분이고, springdoc-openapi-ui는 Spring Boot 애플리케이션과 함께 사용하기 쉽게 설계되었기 때문에 많은 개발자들이 선택하는 기본 옵션이다. 만약 나중에 프로젝트가 WebFlux를 사용하게 되거나, 다른 프로젝트에서 SpringDoc을 사용해야 할 경우 springdoc-openapi-ui가 더 범용적으로 활용될 수 있다.

결론적으로, 당신이 특정한 스프링 프레임워크 스타일(MVC)에 제한되지 않고 좀 더 범용적인 설정을 선호한다면 springdoc-openapi-ui를 사용하는 게 맞다.

 

나는 springdoc-opanapi-ui를 선택했다.

 

 

💡 2번(외부 설정), 3번(Swagger 설정 클래스 구현), 4번(컨트롤러에 Swagger 어노테이션 적용), 5번(DTO에 Swagger 어노테이션 적용) 항목은 전부 선택 사항이다.

Swagger 3을 사용할 때, Swagger 2와 달리 많은 경우 기본 설정만으로도 Swagger UI를 통해 API 문서를 볼 수 있다. Spring Boot와 Springdoc 라이브러리를 사용하면, 특별한 설정 없이도 http://localhost:{port}/swagger-ui/index.html 주소로 접속하면 자동으로 API 문서가 생성되고, UI가 제공된다.

 

 

2. 외부 설정 (선택 사항)

• application.yml의 설정은 다음과 같은 이유로 필요하다.
  • API 문서의 경로나 UI의 경로를 기본값에서 변경하고 싶을 때
  • API 문서를 정렬하거나, 특정 태그를 그룹화하고 싶을 때
  • API의 버전 정보나 설명을 추가하고 싶을 때
  • 보안 설정이나 다른 고급 설정을 적용하고 싶을 때
• 만약 단순히 기본 설정으로도 충분하다면, application.yml에 추가 설정을 하지 않고도 Swagger UI와 OpenAPI 문서를 사용할 수 있다. 하지만 더 세밀한 제어를 원하거나, 프로젝트의 특정 요구사항을 충족시키고 싶다면 application.yml에서 해당 설정을 해주는 것이 좋다.

springdoc:
  swagger-ui:
    path: /swagger-ui.html # Swagger HTML 문서 경로
    groups-order: DESC
    operationsSorter: alpha # API 메서드 정렬 순서 (alpha: 알파벳순, method: HTTP 메서드 순)
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /api-docs # OpenAPI 3으로 JSON 형식의 API 문서 경로
  version: sample-project-backend.v0.1
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

 

• path: /swagger-ui.html:
  • Swagger UI에 접근할 수 있는 경로를 설정한다.
  • 만약 기본 경로(/swagger-ui/index.html)가 아닌 다른 경로를 사용하고 싶을 때 유용하다.
• groups-order: DESC
  • API 문서의 그룹 순서를 내림차순으로 정렬한다.
  • API 그룹을 정렬하는 방식을 제어하고 싶을 때 적용한다.
• operationsSorter: alpha
  • API 문서 내의 연산을 알파벳 순으로 정렬한다.
  • API를 더 읽기 쉽게 만들고 싶을 때, 특히 많은 연산이 있을 때 유용하다.
• disable-swagger-default-url: true
  • Swagger UI가 로딩될 때 기본적으로 제공되는 URL을 비활성화한다.
  • 사용자 정의 URL을 사용하고 싶거나 기본 URL을 숨기고 싶을 때 사용한다.
  • 이 값을 true로 설정했다면 실제 접속하는 URL은 swagger-ui.path 설정에 의해 결정된다.
• display-request-duration: true
  • API 호출의 응답 시간을 Swagger UI에 표시한다.
  • API 응답 속도를 모니터링하고 싶을 때 도움이 된다.
• api-docs: path: api-docs
  • OpenAPI 3.0 사양에 따라 생성된 API 문서의 경로를 설정한다.
  • 기본 경로(/v3/api-docs)를 변경하고 싶을 때 사용한다.
  • 이 경로는 Spring Boot 어플리케이션 내부에서 사용된다.
  • 이 설정은 실제로 Swagger가 생성하는 JSON 형식의 API 문서에 접근할 때 사용하는 URL 경로를 정의한다.
  • 예를 들어, path: /api-docs로 설정했다면, API 문서를 JSON 형식으로 받아보기 위한 URL은 http://localhost:{port}/api-docs가 될 것이다. 여기서 {port}는 서버를 실행하고 있는 실제 포트 번호로 대체된다.
  • 이 경로를 통해, OpenAPI 사양을 따르는 API 문서를 얻을 수 있고, 이 문서는 Swagger UI나 다른 클라이언트에서 API를 시각화하거나 소비하기 위한 기초 자료로 사용될 수 있다.
• version: sample-project-backend.v0.1
  • 문서에 표시될 API의 버전을 설정한다.
  • 프로젝트의 버전을 문서화하고 싶을 때 유용하다.
• show-actuator: true
  • Spring Boot의 액추에이터 엔드포인트를 문서화한다.
  • 애플리케이션의 상태나 메트릭스를 API 문서에 포함시키고 싶을 때 사용한다.
• default-consumes-media-type: application/json
  • API가 기본적으로 받아들이는 미디어 유형을 설정한다.
  • 대부분의 API 연산이 JSON 형식의 데이터를 받을 때 설정한다.
• default-produces-media-type: application/json
  • API가 기본적으로 생성하는 미디어 유형을 설정한다.
  • API 응답이 주로 JSON 형식일 때 설정한다.

 

❗ 근데 나중에 내가 설정한 path로 접속해도 자동으로 url이 http://localhost:{port}/swagger-ui/index.html로 리다이렉트 될것이다.

springdoc.swagger-ui.path: /swagger-ui.html 그리고 disable-swagger-default-url: true 이 두가지를 전부 추가해줬는데 왜 http://localhost:{port}/swagger-ui.html 여기로 접속했을때 자동으로 url이 http://localhost:{port}/swagger-ui/index.html 로 리다이렉트 되는걸까?

이 동작은 사실 SpringDoc 라이브러리에서 일반적으로 볼 수 있는 것이며, "정상"으로 간주된다.
springdoc.swagger-ui.path 설정은 Swagger UI에 접근하기 위한 URL 경로를 지정하지만, 실제로 Swagger UI가 호스팅되는 위치는 /swagger-ui/index.html이다.
disable-swagger-default-url: true 설정은 Swagger UI가 로드될 때 기본적으로 제공되는 URL을 입력 필드에 자동으로 채우지 않도록 하는 것이다. 이 설정은 Swagger UI 페이지 내에서 사용되는 기본 URL을 비활성화하는 것이지, Swagger UI 자체의 경로를 변경하지 않는다.

따라서 http://localhost:{port}/swagger-ui.html로 접속했을 때 http://localhost:{port}/swagger-ui/index.html로 리다이렉트되는 것은 SpringDoc이 Swagger UI를 서비스하는 표준 메커니즘이다. 이 리다이렉트는 사용자가 더 친숙한 .html 확장자를 사용하여 접근할 수 있도록 하기 위해 설정되어 있는 것이며, 이는 Swagger UI의 내부 동작 방식에 따른 것이다.

 

 

이러한 설정은 API 문서와 UI를 더 명확하고 직관적으로 만들며, 개발자와 사용자가 API를 더 쉽게 이해하고 사용할 수 있도록 돕는다.

 

 

3. Swagger 설정 클래스 구현 (선택 사항)

•  이 설정 클래스를 통해 OpenAPI 사양을 사용자 정의할 수 있으며, 여기에는 API 문서의 제목, 설명, 버전 등의 정보를 설정할 수 있다.
• 이 정보는 Swagger UI에 표시되는 API 문서의 메타데이터 부분에 반영된다.

 

• OpenApiConfig 설정 클래스를 사용하지 않으면, Springdoc은 기본 메타데이터 정보를 사용하여 API 문서를 생성한다.
• 하지만 이 클래스를 사용하면 다음과 같은 이점이 있다:
  • 정보 맞춤화: API 문서의 title, description, version 등을 원하는 대로 설정할 수 있어, 문서가 더 명확하고 전문적으로 보인다.
  • 확장성: 추후에 API 문서에 더 많은 정보나 설정을 추가하고 싶을 때, 이 클래스를 확장하여 새로운 설정을 쉽게 추가할 수 있다.
  • 유지보수성: API 문서화 관련 설정이 한 곳에 모여 있어서, 관리 및 유지보수가 편리하다.
  •  

 

따라서 OpenApiConfig 설정 클래스는 필수적인 것은 아니지만, API 문서를 더 세밀하게 제어하고, 전문성을 더하며, 향후 확장성을 고려할 때 유용하다.

 

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

/**
 * Swagger 설정 클래스
 */
@Configuration // 이 클래스가 설정 파일임을 나타냄
public class OpenApiConfig {

    @Bean // 이 메서드가 Spring 컨테이너에 의해 빈으로 등록될 것임을 나타냄
    public OpenAPI openAPI(@Value("${springdoc.version}") String springdocVersion) {
        // API 문서의 정보를 설정하는 Info 객체 생성
        Info info = new Info()
                .title("Sample Project") // API 문서의 제목 설정
                .version(springdocVersion) // `application.yml`에서 가져온 버전 정보로 버전 설정
                .description("This is Sample Project Description."); // API 문서의 설명 설정

        // OpenAPI 객체를 생성하고, info 객체로 API 문서의 메타데이터를 설정함
        return new OpenAPI()
                .components(new Components()) // 현재는 비어있는 Components 객체를 설정하지만, 필요에 따라 여기에 재사용 가능한 구성요소들을 추가할 수 있음
                .info(info); // 설정한 Info 객체를 OpenAPI 객체에 적용
    }
}

 

 

 

4. 컨트롤러에 Swagger 어노테이션 적용 (선택 사항)

• 이 어노테이션들은 API 문서에 더 상세한 정보를 추가하고, 개발자가 API를 더 잘 이해하도록 도와준다.

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.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;


@Tag(name = "Tag-name", description = "this is the description.")
// 이 태그는 Swagger UI에서 이 컨트롤러에 대한 설명과 이름을 그룹화하는 데 사용된다.
@RestController
public class SampleController {

    @Operation(summary = "summary", description = "description")
    // 이 어노테이션은 특정 API 연산에 대한 요약과 설명을 제공한다.
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "요청 성공")
    })
    // 이 어노테이션은 API 응답에 대한 정보를 제공한다. 예를 들어, HTTP 상태 코드 200이 성공적인 응답을 나타낸다고 문서화한다.
    @PostMapping("/req")
    public ResponseEntity<ResponseDto<String>> req(    
        // @Parameter 어노테이션은 요청 파라미터에 대한 정보를 제공한다. 여기서는 "param1"이 필수 파라미터임을 명시한다.
        @Parameter(name = "파라미터1", description = "파라미터1", required = true) 
        @RequestParam(value = "param1") Integer param1
    ) {
        // 이 메서드는 API의 실제 로직을 처리한다.

        return ResponseEntity.ok().body(
                ResponseDto.<String>builder()
                        .data("This is the result")
                        .message("success")
                        .build()
        );
    }

}

 

 

5. DTO에 Swagger 어노테이션 적용 (선택 사항)

import io.swagger.v3.oas.annotations.media.Schema;

@ToString
@AllArgsConstructor
@NoArgsConstructor
@Data
// UserDTO 클래스에 대한 Swagger 문서 정보를 정의합니다.
@Schema(description = "사용자 정보를 전달하는 데이터 전송 객체")
public class UserDto {

    @Schema(description = "사용자의 고유 식별자", example = "1", required = true)
    private Long id;

    @Schema(description = "사용자의 이름", example = "홍길동", required = true)
    private String name;

    @Schema(description = "사용자의 이메일 주소", example = "honggildong@example.com", required = true)
    private String email;

}

 

• 이 UserDto 클래스는 사용자의 정보를 나타내는 단순한 데이터 전송 객체로서, @Schema 어노테이션을 사용하여 Swagger 문서에 포함될 각 필드의 설명과 예제 값을 제공한다.
• 이렇게 함으로써, API 문서를 보는 사람은 각 필드가 어떤 값을 가지며, 어떤 형태로 데이터가 전달되는지 쉽게 이해할 수 있다.
• required = true는 해당 필드가 필수적임을 나타내어, API를 사용할 때 이 필드가 반드시 포함되어야 함을 명시한다.

 

 

6. Swagger UI 접속

• 부가적인 설정을 적용하지 않았다면
  • 웹 브라우저에서 http://localhost:{port}/swagger/index.html로 접속한다.
• application.yml에서 springdoc.swagger-ui.path 설정을 수정했다면 
  • 웹 브라우저에서 http://localhost:{port}/새로 지정한 path로 접속한다.

 

• 나는 부가적인 설정을 해주었기 때문에 아래와 같은 화면이 보인다.

OpenApiConfig 설정이 적용된 모습

Controller의 Swagger 어노테이션이 적용된 모습

 

 

7. 마무리

이상으로 Swagger 3에 대한 탐구를 마치며, 이 글이 여러분에게 유익한 여정이었기를 바란다.

 

처음에는 몇 줄의 설정 코드로 시작되는 간단한 작업처럼 보였지만, 실제로는 Swagger의 세계로 한 걸음 더 깊이 들어가는 기회가 되었다. 이번 기회를 통해 Swagger가 단순한 문서 도구를 넘어서 개발자와 사용자 간의 소통을 원활하게 하고, API의 세계를 더 넓게 열어주는 중요한 역할을 한다는 것을 깊이 이해하게 되었다.

 

이러한 지식을 통해 앞으로 더 풍부하고 완성도 높은 API를 설계할 수 있을 것이라 기대한다.