Java 11 Quarkus中如何自定义注解合并重复@APIResponse？

这个方案完全可行，Quarkus 2.9.2 基于的SmallRye OpenAPI支持通过自定义组合注解来复用重复的@APIResponse配置，这是减少接口文档注解冗余的常用手段。

1. 自定义组合注解@APIResponses40X #

创建一个新的注解类，用@APIResponses包裹你需要复用的三个@APIResponse，同时指定注解的保留策略和作用目标：

import io.swagger.v3.oas.annotations.responses.APIResponse;
import io.swagger.v3.oas.annotations.responses.APIResponses;
import jakarta.ws.rs.core.MediaType;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

// 指定注解可作用在方法或类上
@Target({ElementType.METHOD, ElementType.TYPE})
// 保留到运行时，让OpenAPI处理器能识别解析
@Retention(RetentionPolicy.RUNTIME)
// 包裹需要复用的三个API响应配置
@APIResponses({
    @APIResponse(
        responseCode = "401",
        description = "Unauthorized",
        content = @io.swagger.v3.oas.annotations.media.Content(mediaType = MediaType.APPLICATION_JSON)
    ),
    @APIResponse(
        responseCode = "403",
        description = "Forbidden",
        content = @io.swagger.v3.oas.annotations.media.Content(mediaType = MediaType.APPLICATION_JSON)
    ),
    @APIResponse(
        responseCode = "404",
        description = "Not Found",
        content = @io.swagger.v3.oas.annotations.media.Content(mediaType = MediaType.APPLICATION_JSON)
    )
})
public @interface APIResponses40X {
}

如果更倾向于使用Quarkus适配的OpenAPI注解，也可以替换为io.quarkus.smallrye.openapi.runtime.api.annotations下的OpenAPIResponse和OpenAPIResponses，功能完全一致，适配性更好。

2. 在接口中使用自定义注解 #

在需要的REST接口方法或类上直接添加@APIResponses40X，即可替代原来的三个@APIResponse：

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/users")
public class UserResource {

    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    @APIResponses40X // 直接复用组合注解
    public User getUserById(String id) {
        // 业务逻辑实现
        return new User();
    }
}

3. 验证效果 #

启动Quarkus应用后，访问默认的OpenAPI文档页面（/q/openapi或/q/swagger-ui），可以看到目标接口已自动包含401、403、404这三个响应的文档描述，和直接添加三个@APIResponse的效果完全一致。

内容的提问来源于stack exchange，提问作者kadir_j