Swagger 生成的 REST API 文档根据需要显示查询参数（但我不需要）答案

【问题标题】：Swagger generated REST API docs showing query params as required (but I want not-required)Swagger 生成的 REST API 文档根据需要显示查询参数（但我不需要）
【发布时间】：2023-04-11 05:30:02
【问题描述】：

我正在为我的 REST API 生成 swagger 文档。生成的文档显示参数是必需的。如何让他们 not-required 招摇？在实际的 REST 调用中，它们不是必需的（如预期的那样）；所以问题只是在文档中。

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有

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

【问题讨论】：

标签： rest swagger

【解决方案1】：

@ApiParam 注释可以解决问题。来自大摇大摆documentation：

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

根据javadoc，可以使用required来指定是否需要参数。要使用它，请执行以下操作：

@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了解更多详情。

【讨论】：

谢谢。确实，看起来它应该完全按照我的意愿做，但是在我刚才的测试中，它没有任何区别，即我仍然在生成的 swagger.json 中看到 "required":true ！
@k1eran 你用的是什么版本？ current stable version is 1.5.4。旧版本中 @ApiParam was reported 的问题。
事实证明，我的项目正在使用它自己的自定义 maven-plugin 来生成 swagger.json 文件（有点类似于 github.com/swagger-api/swagger-codegen/blob/master/modules/… ），不幸的是忽略了特定于 swagger 的注释 @ApiParam 并使用不同的方法来检测 "required":true 是需要的。（我仍然不确定为什么我的项目采用这种方法；但是，由于您的建议是“标准”招摇设置的正确解决方案...谢谢，我接受您的回答。