如何为基于查询参数、用Response Builder构建响应的通用JAX-RS API集成Swagger？

1. 添加Swagger依赖 #

首先在项目构建文件中引入Swagger JAX-RS相关依赖，以Maven为例：

<dependencies>
    <!-- Swagger Core -->
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-core</artifactId>
        <version>2.2.20</version>
    </dependency>
    <!-- Swagger JAX-RS2 -->
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.2.20</version>
    </dependency>
    <!-- Swagger UI（可选，用于可视化API文档） -->
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>5.17.14</version>
    </dependency>
</dependencies>

2. 注册Swagger资源 #

在JAX-RS的Application子类中注册Swagger核心资源，让应用识别Swagger的API文档生成逻辑：

import io.swagger.v3.jaxrs2.integration.resources.OpenApiResource;
import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;
import java.util.HashSet;
import java.util.Set;

@ApplicationPath("/api")
public class JaxRsApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> resources = new HashSet<>();
        // 注册自定义API资源
        resources.add(DataResource.class);
        // 注册Swagger资源
        resources.add(OpenApiResource.class);
        return resources;
    }
}

3. 编写集成Swagger的JAX-RS API示例 #

以下是基于查询参数、使用Response Builder构建响应体的完整API示例，包含Swagger注解以生成规范的API文档：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.List;

@Path("/data")
public class DataResource {

    @GET
    @Operation(
        summary = "按类别查询数据",
        description = "根据传入的类别参数和数量限制，动态生成并返回JSON格式的数据列表"
    )
    @ApiResponse(
        responseCode = "200",
        description = "查询成功，返回数据列表",
        content = @Content(
            mediaType = MediaType.APPLICATION_JSON,
            schema = @Schema(implementation = DataResponse.class)
        )
    )
    @ApiResponse(
        responseCode = "400",
        description = "请求参数不合法，类别参数不能为空"
    )
    public Response fetchData(
        @Parameter(description = "数据类别（必填）", required = true)
        @QueryParam("category") String category,
        
        @Parameter(description = "返回数据的最大数量，默认值为10")
        @QueryParam("limit") Integer limit
    ) {
        // 处理参数默认值
        int finalLimit = limit == null ? 10 : limit;
        
        // 参数合法性校验
        if (category == null || category.isBlank()) {
            return Response.status(Response.Status.BAD_REQUEST)
                          .entity("类别参数category不能为空")
                          .type(MediaType.TEXT_PLAIN)
                          .build();
        }
        
        // 模拟生成业务数据
        DataResponse responseBody = new DataResponse();
        responseBody.setCategory(category);
        responseBody.setLimit(finalLimit);
        responseBody.setItems(List.of("数据项1", "数据项2", "数据项3", "数据项4", "数据项5")
                                  .subList(0, Math.min(finalLimit, 5)));
        
        // 使用Response Builder构建响应
        return Response.ok()
                      .entity(responseBody)
                      .type(MediaType.APPLICATION_JSON)
                      .build();
    }

    // 响应体实体类，供Swagger识别结构
    public static class DataResponse {
        private String category;
        private Integer limit;
        private List<String> items;

        // Getter和Setter方法
        public String getCategory() { return category; }
        public void setCategory(String category) { this.category = category; }
        public Integer getLimit() { return limit; }
        public void setLimit(Integer limit) { this.limit = limit; }
        public List<String> getItems() { return items; }
        public void setItems(List<String> items) { this.items = items; }
    }
}

4. 访问Swagger UI #

项目部署后，可通过以下路径访问可视化的API文档（路径根据你的ApplicationPath调整）：
http://<host>:<port>/api/swagger-ui/index.html

在UI中可以直接查看API的参数说明、响应结构，还能发起测试请求。

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