Swagger：如何记录仅由拦截器/过滤器使用且不会出现在方法签名中的 HTTP 标头参数

Question

我有一个 Jersey REST 方法，并且有一个自定义过滤器，该过滤器作为 REST 方法的注释应用：

@Priority(FilterPriorities.USER_ID_VALIDATOR)
@Provider
@UserIdCheck
public class UserIdValidatorFilter implements ContainerRequestFilter {

    @Override
    public void filter(final ContainerRequestContext requestContext) throws IOException {
        // checks presence of user-id
        ...

        // checks presence of sso-token
        String ssoToken = requestContext.getHeaderString(CustomHttpHeader.SSO_TOKEN);
        ...

        // validates SSO token against used ID
        ...
    }
}

这是我的 REST 方法：

@POST
@Path("/upload")
@Consumes(ExtendedMediaType.MULTIPART_FORM_DATA)
@ApiOperation(
        value = "Saves the uploaded image",
        notes = "Returns the unique id of the image.",
        response = String.class)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "The uploaded image has been saved.", response = String.class),
        @ApiResponse(code = FileTooLargeException.HTTP_STATUS, message = FileTooLargeException.SWAGGER_API_RESPONSE_MESSAGE, response = ErrorInfo.class),
        @ApiResponse(code = InvalidMediaTypeError.HTTP_STATUS, message = InvalidMediaTypeError.SWAGGER_API_RESPONSE_MESSAGE, response = ErrorInfo.class),
        @ApiResponse(code = MissingHttpHeaderException.HTTP_STATUS, message = MissingHttpHeaderException.SWAGGER_API_RESPONSE_MESSAGE, response = ErrorInfo.class),
        @ApiResponse(code = UnauthorizedRequestException.HTTP_STATUS, message = UnauthorizedRequestException.SWAGGER_API_RESPONSE_MESSAGE, response = ErrorInfo.class)})
@UserIdCheck
@Override
public String uploadImage(
        @ApiParam(value = "id of the authenticated user", required = true) @HeaderParam(CustomHttpHeader.USER_ID) final Long userId,
        @ApiParam(value = "file to upload", required = true) @FormDataParam("file") final InputStream inputStream,
        @ApiParam(value = "details of the uploaded file", required = true) @FormDataParam("file") final FormDataContentDisposition fileDetail) {

        // do something here...
    }
}

我的自定义注释 (

@UserIdCheck

) 检查 sso 令牌是否出现在 HTTP 标头上以及它是否有效。

我的问题是，REST 方法不使用此 SSO 令牌，因此它不会出现在方法签名上，但它需要出现在 HTTP 标头上，否则 HTTP 请求将被过滤器阻止。

我无法通过 swagger UI 发出有效的测试请求，因为 SSO_TOKEN 字段没有出现在 Swagger 测试页面上。当然，Swagger 文档中缺少这个重要字段。

我不想将此变量添加到方法签名中，因为它仅由过滤器使用，并且我不需要在方法主体中使用此值。

使用 Swagger 处理此用例的正确方法是什么？

Answer 1

为您的方法使用注释

@ApiImplicitParam(name = "SSO_TOKEN", value = "Access Token", paramType = "header", defaultValue = "sso_access_token")

https://docs.swagger.io/swagger-core/current/apidocs/io/swagger/annotations/ApiImplicitParam.html