Reputation: 2040
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
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