CODEWITHSUNDEEP
javamavenswaggeropenapi
Carsten
Carsten

Reputation: 2040

QueryParam declared as not required in Swagger API

I have implemented a Jax-RS resource (using Dropwizard) which contains this method:

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);
}

In my pom.xml, I have added the swagger-maven-plugin like this:

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

When I run mvn compile, it creates the swagger.json file containing these entries:

"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
    } ],
[...]

This is all fine, except one line in the content parameter definition:

      "required" : false,

However, the content field is clearly required. This is also confirmed when I call the service: if the content parameter is not provided, it throws an error.

From this answer, it seems like I could explicitly state that the parameter is required by using the Swagger @ApiParam annotation. However, I would prefer not to introduce additional code and dependencies only for the purpose of the Swagger API definition.

This looks like a rather minor problem, but it might indicate a bug in my code or even in the swagger-maven-plugin. Have I missed anything?

Does the Swagger plugin does not recognize the @org.hibernate.validator.constraints.NotEmpty annotation? If it does not, is the Swagger @OpenAPI parameter the only way to declare a parameter as required for the Swagger plugin?

Upvotes: 1

Views: 4513

Answers (1)

Carsten
Carsten

Reputation: 2040

The only working solution I have found is to indeed use the @ApiParam annotation like this:

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


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

Of course, this requires an additional Swagger dependency (in pom.xml):

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

Upvotes: 1

Related Questions