Swagger API 中声明为不需要的 QueryParam答案

【问题标题】：QueryParam declared as not required in Swagger APISwagger API 中声明为不需要的 QueryParam
【发布时间】：2018-09-07 08:25:21
【问题描述】：

我已经实现了一个包含此方法的 Jax-RS 资源（使用 Dropwizard）：

import javax.ws.rs.DefaultValue;
import javax.ws.rs.HeaderParam;
import javax.ws.rs.POST;
import javax.ws.rs.QueryParam;
import org.hibernate.validator.constraints.NotEmpty;
[...]

@POST
@Timed
public Prediction predict(
        @QueryParam("content") @NotEmpty String content,
        @HeaderParam("outputProbability") @DefaultValue("false") Boolean outputProbability) {
    return outputProbability ? getPredictionWithProb(content) : getPrediction(content);
}

在我的pom.xml 中，我添加了swagger-maven-plugin，如下所示：

        <plugin>
            <groupId>com.github.kongchen</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>${swagger-maven-plugin-version}</version>
            <configuration>
                <apiSources>
                    <apiSource>
                        <springmvc>false</springmvc>
                        <schemes>
                            <scheme>http</scheme>
                        </schemes>
                        <locations>[...]</locations>
                        <info>[...]</info>
                        <swaggerDirectory>src/main/resources/swagger</swaggerDirectory>
                    </apiSource>
                </apiSources>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

当我运行mvn compile 时，它会创建包含这些条目的swagger.json 文件：

"paths" : {
"/predict" : {
  "post" : {
    "operationId" : "predict",
    "produces" : [ "application/json" ],
    "parameters" : [ {
      "name" : "content",
      "in" : "query",
      "required" : false,
      "type" : "string"
    }, {
      "name" : "outputProbability",
      "in" : "header",
      "required" : false,
      "type" : "boolean",
      "default" : false
    } ],
[...]

这一切都很好，除了content参数定义中的一行：

      "required" : false,

但是，content 字段显然是必需的。这一点在我调用服务的时候也得到了证实：如果没有提供content参数，就会抛出错误。

从this answer 看来，我可以使用 Swagger @ApiParam annotation 明确声明该参数是必需的。但是，我不希望仅出于 Swagger API 定义的目的而引入额外的代码和依赖项。

这看起来是一个很小的问题，但它可能表明我的代码甚至 swagger-maven-plugin 中存在错误。我错过了什么吗？

Swagger 插件是否无法识别@org.hibernate.validator.constraints.NotEmpty 注释？如果不是，那么 Swagger @OpenAPI 参数是声明 Swagger 插件所需参数的唯一方法吗？

【问题讨论】：

您必须检查这个，但 Swagger 可能会将其视为“不需要”，因为它是默认值，如果未提供则将使用它
@DamCx content 参数如何有默认值？我没有指定一个。只有outputProbability 有一个。

标签： java maven swagger openapi

【解决方案1】：

我发现的唯一可行的解决方案是确实像这样使用@ApiParam 注释：

import io.swagger.annotations.ApiParam;
[...]


@POST
@Timed
public Prediction predict(
        @QueryParam("content") @NotEmpty @ApiParam(required = true) String content,
        @HeaderParam("outputProbability") @DefaultValue("false") Boolean outputProbability) {

当然，这需要额外的 Swagger 依赖（在 pom.xml 中）：

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>

【讨论】：