QueryParam объявлен как необязательный в Swagger API

Я реализовал ресурс 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 не указан, она выдает ошибку.

Из этот ответ кажется, что я мог бы явно указать, что параметр требуется с помощью Swagger аннотация @ApiParam. Однако я бы предпочел не вводить дополнительный код и зависимости только для целей определения Swagger API.

Это выглядит как довольно незначительная проблема, но это может указывать на ошибку в моем коде или даже в файле swagger-maven-plugin. Я ничего не пропустил?

Плагин Swagger не распознает аннотацию @org.hibernate.validator.constraints.NotEmpty? Если это не так, является ли параметр Swagger @OpenAPI единственным способом объявить параметр, необходимый для плагина Swagger?


person Carsten    schedule 07.09.2018    source источник
comment
Вам нужно будет проверить это, но Swagger может счесть это необязательным, поскольку это значение по умолчанию, которое будет использоваться, если ничего не указано.   -  person DamCx    schedule 07.09.2018
comment
@DamCx Как параметр content имеет значение по умолчанию? Я не указал ни одного. Он есть только у outputProbability.   -  person Carsten    schedule 07.09.2018


Ответы (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>
person Carsten    schedule 07.09.2018