QueryParam 在 Swagger 中声明为不需要 API

Question

我已经实现了包含此方法的 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 参数，则会引发错误。

来自 , it seems like I could explicitly state that the parameter is required by using the Swagger @ApiParam annotation。但是，我不想仅出于 Swagger API 定义的目的而引入额外的代码和依赖项。

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

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

Answer 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>

QueryParam 在 Swagger 中声明为不需要 API

QueryParam declared as not required in Swagger API

java

maven

swagger

openapi