如何基于 Swagger 的自定义注释创建注释/描述

Question

我有一个 Springboot Rest 应用程序，其中有自动转换 API 和参数的注释。

我有自定义注释，其中包含一些注释，如何将其生成到 OpenAPI 3 中的 swagger 页面？

Ex:
@RestController
Class Controller {

@GetMapping(/test/result/)
@CustomAnnotation(value = "This description should come in swagger")
void method() {
}
}

Answer 1

SpringDoc 允许您通过实现自己的定制器 bean 来定制生成的 OpenAPI 规范。

有很多定制器界面可用于定制，但最有用的是

OperationCustomizer

、

ParameterCustomizer

和

PropertyCustomizer

。

下面是适合您的用例的操作定制器示例。

@Component
public class OperationCustomizer implements org.springdoc.core.customizers.OperationCustomizer {
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        CustomAnnotation annotation = handlerMethod.getMethodAnnotation(CustomAnnotation.class);
        if (annotation != null) {
            operation.description(annotation.value());
        }
        return operation;
    }
}

在这里您可以找到使用自定义注释和定制器的项目示例。

这里是一个基于@NonNull注释修改生成规范的项目示例。

Answer 2

正如 @VadymVL 指出的，扩展

OperationCustomizer

的组件是必要的：

@Component
public class CustomOperationCustomizer implements OperationCustomizer {
  @Override
  public Operation customize(Operation operation, HandlerMethod handlerMethod) {
      /* your code */
  }

只是不要忘记注册：

@Bean
  public GroupedOpenApi publicApi(CustomOperationCustomizer operationCustomizer) {
    return GroupedOpenApi.builder()
            .group(/*your group*/)
            .pathsToMatch(/*your endpoint*/)
            .
            /* anything else you need */
            .
            .addOperationCustomizer(operationCustomizer)
            .build();
  }

你就可以出发了！