Swagger 生成的 REST API 文档根据需要显示查询参数(但我不想要) [英] Swagger generated REST API docs showing query params as required (but I want not-required)

问题描述

我正在为我的 REST API 生成 swagger 文档.生成的文档显示参数是必需的.如何使它们不需要 swagger ?在实际的 REST 调用中，它们不是必需的(如预期的那样)；所以问题只是在文档中.

I am generating swagger docs for my REST API. The generated docs show the params are required. How to make them not-required in swagger ? In actual REST invocations they are not-required (as expected); so problem is just in documentation.

import javax.ws.rs.*;

@GET
@Produces(MediaType.APPLICATION_JSON)
public Response getBaz(
        @DefaultValue("false") @QueryParam("foo") final boolean myFoo,
        @DefaultValue("") @QueryParam("bar") final String myBar
) { ... }

生成的swagger.json有

The generated swagger.json has

... "parameters":[{   ... snip "myBar":"bar","required":true}

推荐答案

@ApiParam 注释可以解决问题.来自 Swagger 文档:

@ApiParam 仅与 JAX-RS 参数注释(@PathParam、@QueryParam、@HeaderParam、@FormParam 和在 JAX-RS 2 中，@BeanParam).虽然 swagger-core 默认扫描这些注释，但 @ApiParam 可用于添加有关参数的更多详细信息或更改从代码中读取的值.[...]

The @ApiParam is used solely with the JAX-RS parameter annotations (@PathParam, @QueryParam, @HeaderParam, @FormParam and in JAX-RS 2, @BeanParam). While swagger-core scans these annotations by default, the @ApiParam can be used to add more details on the parameters or change the values as they are read from the code. [...]

根据 javadoc，您可以使用 required 来指定参数是否是必需的.要使用它，请执行以下操作:

According to the javadoc, you can use required to specify if the parameter is required or not. To use it, do as following:

@GET
@Produces(MediaType.APPLICATION_JSON)
public Response method(@ApiParam(value = "foo", required = false) @QueryParam("foo") boolean foo,
                       @ApiParam(value = "bar", required = false) @QueryParam("bar") String bar) { 
    ...
}

检查 javadoc 了解更多详情.

Check the javadoc for more details.

这篇关于Swagger 生成的 REST API 文档根据需要显示查询参数(但我不想要)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！