javaspring-webfluxspringdoc-openapi-ui

Specifying schema attributes descriptions


Can I describe schema attributes somehow, similar to how I can describe request parameters? In my case, I want to tell the clients that identifier means either a username, email, or phone. Obviously, I don't want to rename the attribute to usernameEmailOrPhone.

import jakarta.validation.constraints.NotBlank;
import lombok.Getter;
import lombok.Setter;

@Setter
@Getter
public class LoginUserRequestDto {
    @NotBlank(message = "Must be present (a user name, email, or phone)")
    private String identifier;
    @NotBlank(message = "Must be present")
    private String password;
}
@Configuration
public class RouterConfig {
    private final TokenHandler tokenHandler;

    public RouterConfig(TokenHandler tokenHandler) {
        this.tokenHandler = tokenHandler;
    }

    @Bean
    @RouterOperation(beanClass = TokenHandler.class, beanMethod = "logIn")
    public RouterFunction<ServerResponse> logIn() {
        return RouterFunctions.route()
                .POST("/login", tokenHandler::logIn)
                .build();
    }
}
// TokenHandler implementation

    @Override
    @Operation(requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = LoginUserRequestDto.class)), required = true))
    @ApiResponse(responseCode = "200", content = @Content(mediaType = "text/plain"))
    public Mono<ServerResponse> logIn(ServerRequest request) {
        return request.bodyToMono(LoginUserRequestDto.class)
                .doOnNext(this::validate)
                .map(UserDtoAuthenticationToken::from)
                .flatMap(authenticationManager::authenticate)
                .ofType(UserAuthenticationToken.class)
                .map(UserAuthenticationToken::getPrincipal)
                .ofType(User.class)
                .map(tokenService::generateTokenFor)
                .transform(jwt -> ServerResponse.status(HttpStatus.OK).body(jwt, String.class));
    }

Solution

  • If you mean, describe so that the description shows up in the OpenAPI YAML or Swagger, then yes, using the @Schema annotation as follows:

    import io.swagger.v3.oas.annotations.media.Schema;
    import jakarta.validation.constraints.NotBlank;
    import lombok.Getter;
    import lombok.Setter;
    
    @Setter
    @Getter
    public class LoginUserRequestDto {
        @NotBlank(message = "Must be present (a user name, email, or phone)")
        @Schema(description = "The username, email or phone")
        private String identifier;
        @NotBlank(message = "Must be present")
        private String password;
    }