为 Open Api v3 使用 @Schema 注释

Question

我正在尝试将 Swagger2 更改为 OpenApi3，我做的第一件事是将注释 @ApiModel 和 @ApiModelProperty 更改为 @Schema。我使用 'swagger-message.properties' 文件，因为我需要将我的西里尔符号放在那里。这是我的设置豆：

public OpenAPI customOpenAPI(BuildProperties buildProperties) {
    return new OpenAPI()
        .info(new Info()
        .title("bundle-ws")
        .version(buildProperties.getVersion())
        .description("Bundle Ws"));
}

@Bean
public GroupedOpenApi bundleApi() {
    return buildGroupedOpenApi("Bundle", "/bundle/**");
}

@Bean
public TranslationOperationCustomizer translationOperationCustomizer() {
    return new TranslationOperationCustomizer();
}

@Bean
public TranslationSchemaCustomizer translationSchemaCustomizer() {
   return new TranslationSchemaCustomizer();
}

private GroupedOpenApi buildGroupedOpenApi(String group, String... pathsToMatch) {
    return GroupedOpenApi.builder().group(group)
        .pathsToMatch(pathsToMatch)
        .addOperationCustomizer(translationOperationCustomizer())
        .build();
}

@Bean
public ResourceBundleMessageSource translator() {
    ResourceBundleMessageSource source = new ResourceBundleMessageSource();
    source.setBasenames("swagger-message");
    source.setUseCodeAsDefaultMessage(true);
    source.setDefaultEncoding("utf-8");
    return source;
}

public static class TranslationOperationCustomizer implements OperationCustomizer {

    @Autowired
    protected MessageSource translator;

    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        operation.setSummary(translate(operation.getSummary()));
        operation.getResponses().values().forEach(apiResponse -> apiResponse.setDescription(translate(apiResponse.getDescription())));
        return operation;
    }

    private String translate(String message) {
        return translator.getMessage(message, null, message, Locale.getDefault());
    }
}

public static class TranslationSchemaCustomizer implements PropertyCustomizer {

    @Autowired
    protected MessageSource translator;

    @Override
    public Schema customize(Schema property, AnnotatedType type) {
        property.setDescription(translate(property.getDescription()));
        return property;
    }

    private String translate(String message) {
        return translator.getMessage(message, null, message, Locale.getDefault());
    }
}

这是我的 class 我想在 SwaggerUI 中显示：

@Schema(description = "ErrorResponse")
@Data
public class ErrorResponse {

    @Schema(description = "ErrorCode", required = true)
    private final Integer errorCode;

    @Schema(description = "ErrorMessage")
    private final String errorMessage;
}

ErrorResponse、ErrorCode 和 ErrorMessage 是我的属性文件的参数：

ErrorResponse=Результат обработки запроса при неуспешном ответе
ErrorCode=Код ошибки
ErrorMessage=Сообщение об ошибке

但是这些字段可以被 Swagger 读取，而 class 上的注解无法读取：

如何使 class 的描述与字段的描述一样？

Answer 1

您必须使用 description = "${ErrorResponse}"（添加 $）并将 springdoc.api-docs.resolve-schema-properties 设置为 true.

来源：https://springdoc.org/faq.html

为 Open Api v3 使用 @Schema 注释

Using @Schema annotation for Open Api v3

spring

swagger

spring-boot

openapi

springdoc