如何从对象中提取参数以显示在文档中的参数中

Question

我有以下 API 端点：

@ApiResponses(
    value = {
        @ApiResponse(code = 200, message = "OK",
            responseHeaders = {
                @ResponseHeader(name = "X-RateLimit-Limit", description = "The defined maximum number of requests available to the consumer for this API.", response = Integer.class),
                @ResponseHeader(name = "X-RateLimit-Remaining", description = "The number of calls remaining before the limit is enforced and requests are bounced.", response = Integer.class),
                @ResponseHeader(name = "X-RateLimit-Reset", description = "The time, in seconds, until the limit expires and another request will be allowed in. This header will only be present if the limit is being enforced.", response = Integer.class)
            }
        )
    }
)
@ApiOperation(httpMethod = "GET", hidden = false, nickname = "Get Network Availability in JSON", value = "Get network availability for a product", response = AvailableToPromise.class, position = 1)
@RequestMapping(value = "/{product_id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<?> networkAvailabilityJsonResponse(
    @RequestHeader HttpHeaders headers,
    @PathVariable("product_id") String productId,
    @Valid NetworkAvailabilityCmd cmd,                  //query params
    BindingResult result)
    throws Exception {}
}

某些参数，例如 key 从查询中获取并通过 Spring MVC 映射到此对象。

但是，在 swagger-ui 我端点的参数部分，它向我展示了一些奇怪的事情：

None NetworkAvailabilityCmd 中的变量显示在此参数列表中，并且 cmd 本身显示为位于请求正文中（它实际上位于查询中）。有没有办法隐藏 cmd 并提取此对象内的参数以显示在参数列表中？我希望参数列表看起来像这样（有更多参数）：

如果我在方法端点上使用 @ApiImplicitParams 并写出每个参数，我就可以做到这一点。但是，这个 NetworkAvailabilityCmd 用于许多端点，并且在每个端点上都有参数列表非常混乱。能够从对象中提取变量会更加清晰，并且可以防止人们忘记将整个列表添加到新端点。

我想它需要对 NetworkAvailabilityCmd cmd 的注释，并且可能需要对 class 中的变量进行注释，但我似乎无法在文档中找到我要查找的内容.

谢谢！

Answer 1

我发现添加 @ModelAttribute 的效果很神奇。此注释来自 Spring。

如何从对象中提取参数以显示在文档中的参数中

How to extract parameters from an object to show in parameters in documentation

java

swagger

swagger-ui

swagger-2.0