如何简化Swagger AWS配置中的重复注解

针对你大量API重复配置@Extension(name = "amazon-apigateway-integration")的问题，有几种实用的简化方式：

方案1：自定义可复用的组合注解 #

Java注解不支持继承，但可以通过元注解创建包含公共配置的自定义注解，同时允许传入差异化参数（比如uri）。需要配合Swagger插件解析这个自定义注解，让Swagger识别其中的配置。

步骤1：创建自定义注解 #

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Operation(responses = {
        @ApiResponse(responseCode = "403", content = @Content(mediaType = "application/json"))
})
public @interface AwsHttpProxyApi {
    // 差异化的目标uri
    String uri();
    // 可选：指定HTTP方法，默认自动从@RequestMapping系列注解获取
    String httpMethod() default "";
    // 可选：接口摘要描述
    String summary() default "";
}

步骤2：实现Swagger插件解析自定义注解 #

编写一个OperationBuilderPlugin，将自定义注解中的配置合并到Swagger的Operation对象中，自动补充AWS网关集成的扩展配置：

@Component
public class AwsProxyAnnotationProcessor implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        Optional<AwsHttpProxyApi> proxyAnnotation = context.findAnnotation(AwsHttpProxyApi.class);
        if (proxyAnnotation.isPresent()) {
            AwsHttpProxyApi api = proxyAnnotation.get();
            // 构建AWS网关集成的扩展配置
            Extension integrationExtension = new Extension()
                    .name("amazon-apigateway-integration")
                    .properties(Arrays.asList(
                            new ExtensionProperty().name("type").value("HTTP_PROXY"),
                            new ExtensionProperty().name("httpMethod").value(getHttpMethod(context, api)),
                            new ExtensionProperty().name("uri").value(api.uri())
                    ));

            // 将扩展配置添加到当前接口的Operation中
            context.operationBuilder().extensions(Collections.singletonList(integrationExtension));
            
            // 设置接口摘要（如果自定义注解中指定了）
            if (!api.summary().isEmpty()) {
                context.operationBuilder().summary(api.summary());
            }
        }
    }

    // 优先使用自定义注解指定的httpMethod，否则从@RequestMapping系列注解提取
    private String getHttpMethod(OperationContext context, AwsHttpProxyApi api) {
        if (!api.httpMethod().isEmpty()) {
            return api.httpMethod();
        }
        return context.findAnnotation(RequestMapping.class)
                .map(req -> req.method()[0].name())
                .orElse("POST");
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return DocumentationType.OAS_30.equals(documentationType); // 根据你的Swagger版本调整，比如OAS_20
    }
}

步骤3：在Controller中使用自定义注解 #

现在你的API方法可以大幅简化：

@AwsHttpProxyApi(uri = "http://localhost:9090/addUser", summary = "Add User API")
@PostMapping(value = "addUser")
public ResponseEntity<Object> addUser(Authentication authentication, @RequestBody UserDTO userDTO)
        throws VerificationException {
    // 业务逻辑代码
}

方案2：全局配置+局部覆盖 #

如果大部分API的type=HTTP_PROXY是固定的，只有uri和httpMethod不同，可以通过Swagger的Docket配置全局基础扩展，再在接口中仅补充差异化参数。

步骤1：配置全局扩展 #

在Swagger配置类中，给所有接口添加固定的AWS网关扩展：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("your.controller.package"))
                .paths(PathSelectors.any())
                .build()
                .extensions(Collections.singletonList(
                        new Extension()
                                .name("amazon-apigateway-integration")
                                .properties(Collections.singletonList(
                                        new ExtensionProperty().name("type").value("HTTP_PROXY")
                                ))
                ));
    }
}

步骤2：局部补充差异化参数 #

接口方法中只需配置httpMethod和uri即可：

@Operation(extensions = {
        @Extension(name = "amazon-apigateway-integration", properties = {
                @ExtensionProperty(name = "httpMethod", value = "POST"),
                @ExtensionProperty(name = "uri", value = "http://localhost:9090/addUser")
        })
}, summary = "Add User API", responses = {
        @ApiResponse(responseCode = "403", content = @Content(mediaType = "application/json"))
})
@PostMapping(value = "addUser")
public ResponseEntity<Object> addUser(Authentication authentication, @RequestBody UserDTO userDTO)
        throws VerificationException {
    // 业务逻辑代码
}

方案3：抽离公共响应配置 #

如果所有接口的@ApiResponse配置（比如统一的403响应）也重复，可以单独抽成自定义注解：

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@ApiResponses({
        @ApiResponse(responseCode = "403", content = @Content(mediaType = "application/json"))
})
public @interface CommonApiResponses {
}

然后在Controller类或方法上添加这个注解，省去重复编写相同的响应配置。

内容的提问来源于stack exchange，提问作者Arunkumar Tech Expert