如何将 Swagger 设置为忽略 @Suspended jax-rs bean 方法中的 AsyncResponse@

Question

Swagger-Core似乎将@Suspended最终的AsyncResponse asyncResponse成员解释为请求正文参数。这显然不是故意的，也不是事实。

我想告诉 swagger-core 忽略此参数并将其从 api-docs 中排除。有什么想法吗？

这是我的代码的样子：

@Stateless
@Path("/coffee")
@Api(value = "/coffee", description = "The coffee service.")
public class CoffeeService
{
    @Inject
    Event<CoffeeRequest> coffeeRequestListeners;
    @GET
    @ApiOperation(value = "Get Coffee.", notes = "Get tasty coffee.")
    @ApiResponses({
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 404, message = "Beans not found."),
            @ApiResponse(code = 500, message = "Something exceptional happend.")})
    @Produces("application/json")
    @Asynchronous
    public void makeCoffee( @Suspended final AsyncResponse asyncResponse,
                             @ApiParam(value = "The coffee type.", required = true)
                             @QueryParam("type")
                             String type)
    {
        coffeeRequestListeners.fire(new CoffeeRequest(type, asyncResponse));
    }
}

---

更新：基于答案的解决方案

public class InternalSwaggerFilter implements SwaggerSpecFilter
{
    @Override
    public boolean isOperationAllowed(Operation operation, ApiDescription apiDescription, Map<String, List<String>> stringListMap, Map<String, String> stringStringMap, Map<String, List<String>> stringListMap2) {
        return true;
    }
    @Override
    public boolean isParamAllowed(Parameter parameter, Operation operation, ApiDescription apiDescription, Map<String, List<String>> stringListMap, Map<String, String> stringStringMap, Map<String, List<String>> stringListMap2) {
        if( parameter.paramAccess().isDefined() && parameter.paramAccess().get().equals("internal") )
            return false;
        return true;
    }
}

---

FilterFactory.setFilter(new InternalSwaggerFilter());

---

修订的示例代码片段

...
@Asynchronous
public void makeCoffee( @Suspended @ApiParam(access = "internal") final AsyncResponse asyncResponse,...)
...

Answer 1

快

进到 2016 年，swagger-springmvc 被 springfox 取代（文档可在此处获得）。忽略参数在 springfox 中可用，但由于某种原因未记录：

备选方案 1：全局忽略类型或批注类型，在 Docket 配置中使用.ignoredParameterTypes(...)：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .host(reverseProxyHost)
        .useDefaultResponseMessages(false)
        .directModelSubstitute(OffsetDateTime.class, String.class)
        .directModelSubstitute(Duration.class, String.class)
        .directModelSubstitute(LocalDate.class, String.class)
        .forCodeGeneration(true)
        .globalResponseMessage(RequestMethod.GET, newArrayList(
            new ResponseMessageBuilder()
                .code(200).message("Success").build()
            )
        .apiInfo(myApiInfo())
        .ignoredParameterTypes(AuthenticationPrincipal.class, Predicate.class, PathVariable.class)
        .select()
            .apis(withClassAnnotation(Api.class))
            .paths(any())
        .build();
}

替代 2：使用 @ApiIgnore -注释忽略方法中的单个参数：

@ApiOperation(value = "User details")
@RequestMapping(value = "/api/user", method = GET, produces = APPLICATION_JSON_UTF8_VALUE)
public MyUser getUser(@ApiIgnore @AuthenticationPrincipal MyUser user) {
    ...
}

Answer 2

我用你使用的相同技术解决了这个问题，但用了不同的方法。我没有将其标记为内部，我只是忽略所有类型为 AsyncResponse 的参数，这样我就不需要更新所有方法中的代码来添加访问修饰符。

public class CustomSwaggerSpecFilter implements SwaggerSpecFilter {
    @Override
    public boolean isOperationAllowed(Operation operation, ApiDescription api, Map<String, List<String>> params, Map<String, String> cookies,
            Map<String, List<String>> headers) {
        return true;
    }
    @Override
    public boolean isParamAllowed(Parameter parameter, Operation operation, ApiDescription api, Map<String, List<String>> params,
            Map<String, String> cookies, Map<String, List<String>> headers) {
        if(parameter.dataType().equals("AsyncResponse")) { // ignoring AsyncResponse parameters
            return false;
        }
        return true;
    }
}

这对我来说效果更好。

Answer 3

我认为你必须使用过滤器。下面是一个示例 https://github.com/wordnik/swagger-core/issues/269

也可以用java编码。

Answer 4

另一种方法可能是这样做。

@Bean
public SwaggerSpringMvcPlugin mvPluginOverride() {
    SwaggerSpringMvcPlugin swaggerSpringMvcPlugin = new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo());
    swaggerSpringMvcPlugin.ignoredParameterTypes(PagedResourcesAssembler.class, Pageable.class);
    return swaggerSpringMvcPlugin;
}