[Spring] Swagger 적용(Springboot 3.x)

Swagger 란?

What Is Swagger? Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. 출처 : https://swagger.io/docs/specification/about/ Swagger는 REST API를 설계, 구축, 문서화 및 소비하는 데 도움이 되는 OpenAPI 사양을 기반으로 구축된 오픈 소스 도구 세트입니다:

 

설정 방법

• Maven

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

 

• Gradle

// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

 

버전은 사용하고 싶은 버전을 입력

springdoc : https://springdoc.org/

 

Swagger 적용 확인 방법(접속 방법)

2.x.x 버전: localhost:8080/swagger-ui.html
3.x.x 버전: localhost:8080/swagger-ui/index.html

  

 

SwaggerConfig 설정

• 단독 사용

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.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("API test") // API 제목
                .description("Swagger API") // API 설명
                .version("1.0.0"); // API 버전
    }
}

  

 

 

• 그룹 사용

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = "API test",
        description = "Swagger API",
        version = "1.0.0")
)
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi getItemApi() {

        return GroupedOpenApi
                .builder()
                .group("item")
                .pathsToMatch("/verify-email")
                .build();
    }

    @Bean
    public GroupedOpenApi getMemberApi() {

        return GroupedOpenApi
                .builder()
                .group("member")
                .pathsToMatch("/verification-code")
                .build();
    }
}

 

 

SpringFox 와 SpringDoc의 Annotation

SpringFox	속성	SpringDoc	속성	설명
@Api		@Tag		태그
	tag		name	태그의 이름
	value		description	설명
@ApiModelProperty		@Schema		모델의 속성
	required = true		requiredMode = REQUIRED	필수 항목
	required = false		requiredMode = NOT_REQUIRED	필수X
	value		description	필드 설명
	notes		example	필드 추가 설명
	dataType		type	타입
	position		- (대체 없음. 필드 선언 순으로 나타남)	순서
	allowEmptyValue		nullable	null 가능 여부
@ApiModel		@Schema		모델의 속성
@ApiOperation		@Operation		메소드에 대한 추가 속성 정의
	value		summary	120자 이하의 간략한 요약, 설명
	notes		description	자세한 설명
@ApiParam		@Parameter		매개변수(파라미터)에 대한 주석
	value		description	설명
	defaultValue		schema = @Schema(defaultValue = "")	기본값 설정
@Apilgnore		@Hidden 또는 @Parameter (hidden = true) 또는 @Operation (hiddne = true)		숨김처리

출처 : https://yeonyeon.tistory.com/322

참고 : springdoc-openapi 공식사이트(Migrating from SpringFox)

 

 

---

 

 

참고

https://velog.io/@gmlstjq123/SpringBoot-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-Swagger-UI-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0

https://velog.io/@zosungwoo/Spring-Boot-Spring-Boot-3-%EC%9D%B4%ED%9B%84-Swagger-%EC%A0%81%EC%9A%A9-springdoc-not-springfox

https://yeonyeon.tistory.com/322

https://velog.io/@suzhanlee/Swagger-GroupedOpenApi-%EC%84%A4%EC%A0%95-%EB%B0%A9%EB%B2%95

springdoc-openapi 공식사이트