如何用 Swagger 描述 "ModelAttribute" 的最佳方式

Question

我正在尝试将 Swagger2 集成到我的 Spring 基于引导的应用程序中。问题是 swagger 没有考虑模型属性。

@GetMapping(value = "/events", produces = MediaType.APPLICATION_JSON_VALUE)
public PagedResources<EventResource> getEvents(
        @Valid SearchCriteria searchQuery, 
        BindingResult result, 
        PageableResourcesAssembler<EventResource> assembler){

    // code
}

如您所见，SearchCriteria 是一个 class，它被 Spring 自动绑定。

public class SearchCriteria {

    private List<EventType> eventTypes;

    private LocalDateTime from;

    // getters setters
}

但是 swagger 生成的内容如下：

这不是预期的。期望的结果可能由

注释 getEvents 方法生成

@ApiImplicitParams({
    @ApiImplicitParam(name = "eventTypes", paramType = "query"),
    @ApiImplicitParam(name = "from", paramType = "query")
})
PagedResources<EventResource> getEvents(@ApiParam(hidden = true ) @Valid SearchCriteria searchQuery

但是 @ApiParam(hidden = true ) 不起作用，因为在 Swagger UI 中 searchQuery 参数仍然存在。

---

使用 swagger 描述 POJO 中包含的请求参数的正确方法是什么？对我来说，最好的方法是通过注释 SearchCriteria class 和 @ApiModel 但它不起作用。

Answer 1

这个bug was fixed in Springfox v2.7.0.

---

原答案：

@Valid-annotation 实际上是将参数视为 body-param。

因为这不应该这样做 I've opened an issue on the springfox github page。

but the @ApiParam(hidden = true ) does not work

Springfox 提供了应该工作的 springfox.documentation.annotations.ApiIgnore-注释。

就像this issue中写的那样使用springfox的注释是正确的方法。