Jersey项目Swagger-UI在发送@PathParam时不发送@HeaderParam

在Jersey项目中使用Swagger-UI时，如果遇到@PathParam参数正常传递，但@HeaderParam参数没有被发送的问题，这通常是由于Swagger配置不正确或者客户端请求时没有包含必要的头部信息导致的。

基础概念

@PathParam: 用于从URI路径中提取参数。
@HeaderParam: 用于从HTTP请求头中提取参数。

类型与应用场景

@PathParam: 适用于需要从URL路径中获取信息的场景，如RESTful API中的资源定位。
@HeaderParam: 适用于需要根据请求头信息进行处理的场景，如身份验证、内容协商等。

问题原因及解决方法

原因分析

Swagger配置问题: Swagger可能没有正确地识别或配置@HeaderParam注解。
客户端请求问题: 客户端在发送请求时可能没有包含必要的头部信息。

解决方法

步骤1: 确保Swagger配置正确

确保你的Swagger配置文件（通常是swagger.json或swagger.yaml）中包含了@HeaderParam的相关信息。例如，在Java代码中使用@ApiImplicitParam注解来明确指定头部参数：

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import javax.ws.rs.GET;
import javax.ws.rs.HeaderParam;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Path("/example")
public class ExampleResource {

    @GET
    @Path("/{id}")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "Resource ID", required = true, dataType = "string", paramType = "path"),
        @ApiImplicitParam(name = "X-Custom-Header", value = "Custom Header", required = true, dataType = "string", paramType = "header")
    })
    public String getResource(
        @PathParam("id") String id,
        @HeaderParam("X-Custom-Header") String customHeader) {
        // 处理逻辑
        return "Resource ID: " + id + ", Custom Header: " + customHeader;
    }
}

步骤2: 检查客户端请求

确保客户端在发送请求时包含了必要的头部信息。例如，使用curl命令行工具时，可以这样添加头部信息：

curl -H "X-Custom-Header: someValue" http://example.com/api/example/123

步骤3: 更新Swagger UI

如果Swagger配置文件已经更新，但Swagger UI仍然没有显示正确的参数，可能需要重启Swagger UI服务或者清除浏览器缓存来确保加载最新的配置。

示例代码

以下是一个完整的Jersey资源类示例，展示了如何使用@PathParam和@HeaderParam，并通过Swagger注解进行配置：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import javax.ws.rs.GET;
import javax.ws.rs.HeaderParam;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;

@Path("/example")
@Api(value = "/example", description = "Example API")
public class ExampleResource {

    @GET
    @Path("/{id}")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "Resource ID", required = true, dataType = "string", paramType = "path"),
        @ApiImplicitParam(name = "X-Custom-Header", value = "Custom Header", required = true, dataType = "string", paramType = "header")
    })
    public Response getResource(
        @PathParam("id") String id,
        @HeaderParam("X-Custom-Header") String customHeader) {
        
        // 处理逻辑
        String output = "Resource ID: " + id + ", Custom Header: " + customHeader;
        return Response.status(200).entity(output).build();
    }
}

通过以上步骤和示例代码，应该能够解决Jersey项目中Swagger-UI在发送@PathParam时不发送@HeaderParam的问题。