Swagger 3 (OpenAPI) 설정. 또 바뀌었네.

Swagger 2에서 OpenAPI 3으로 넘어오면서 어노테이션과 설정이 꽤 바뀌었다.

매번 새로 찾아보기 귀찮으니 정리해둔다.

핵심 어노테이션 변경점

Swagger 2 어노테이션은 이제 잊자. OpenAPI 3는 이걸 쓴다.

@Api → @Tag: API 그룹 정의.
@ApiOperation → @Operation: API 설명.
@ApiParam → @Parameter: 파라미터 설명.
@ApiModel, @ApiModelProperty → @Schema: DTO 모델과 속성 설명.

DTO Request/Response 필드 분리

@Schema 어노테이션으로 제어한다. accessMode를 사용하면 된다.


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

// ...

@Schema(description = "사용자 정보 DTO")
public class UserDto {

    @Schema(description = "사용자 ID", accessMode = Schema.AccessMode.READ_ONLY) // 읽기 전용 (응답에만)
    private Long id;

    @Schema(description = "사용자 비밀번호", accessMode = Schema.AccessMode.WRITE_ONLY) // 쓰기 전용 (요청에만)
    private String password;
}

프로필별 활성화 및 서버 URL 변경

이건 이전과 비슷하다. Spring의 @Profile을 사용해서 설정 클래스를 특정 프로필에서만 활성화한다.


@Configuration
@Profile({"local", "stg"}) // local, stg에서만 활성화
public class OpenApiConfig {
    // ...
}

서버 URL 동적 설정은 OpenAPI Bean을 직접 커스터마이징해서 구현한다.


import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Value("${openapi.server.url}")
    private String serverUrl;

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .addServersItem(new Server().url(serverUrl));
    }
}

다중 Swagger 구성 (그룹화)

GroupedOpenApi Bean을 여러 개 만들면 된다. 간단해졌다.


import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi internalApi() {
        return GroupedOpenApi.builder()
                .group("internal-api")
                .pathsToMatch("/internal/**")
                .build();
    }

    @Bean
    public GroupedOpenApi externalApi() {
        return GroupedOpenApi.builder()
                .group("open-api")
                .pathsToMatch("/api/v1/**")
                .build();
    }
}

인증 처리 (JWT Bearer)

인증 설정은 @SecurityScheme 어노테이션으로 정의하는 게 편하다. 설정 클래스에 추가한다.


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

@Configuration
@SecurityScheme(
    name = "Bearer Authentication",
    type = SecuritySchemeType.HTTP,
    bearerFormat = "JWT",
    scheme = "bearer"
)
public class OpenApiConfig {
    // ...
}

그리고 각 API에 @SecurityRequirement를 추가해서 적용한다.


import io.swagger.v3.oas.annotations.security.SecurityRequirement;

@RestController
@SecurityRequirement(name = "Bearer Authentication")
public class MyController {
    // ...
}

이제 UI에서 자물쇠 아이콘을 눌러 토큰을 입력하면 된다.

설정 끝.

퇴근.