Enum in swagger

Question

I'm wondering how to document enums in swagger.

According to JavaDoc

The dataType. See the documentation for the supported datatypes. If the data type is a custom object, set it's name, or nothing. In case of an enum use 'string' and allowableValues for the enum constants.

But I didn't find some good Java example how to really use it, specification is here.

Java

First Service

package betlista.tests.swagger;  import betlista.tests.swagger.model.Input; import betlista.tests.swagger.model.Output; import com.wordnik.swagger.annotations.Api; import com.wordnik.swagger.annotations.ApiOperation;  @Api(value = "first", position = 1) public class RestServiceFirst {      @ApiOperation(value = "foo1 operation", httpMethod = "POST", position = 1, nickname = "foo")     public void foo1(Input input) {      }      @ApiOperation(value = "bar1 operation", response = Output.class, httpMethod = "GET", position = 2, nickname = "bar")     public Output bar1() {         return null;     }  } 

Second Service

package betlista.tests.swagger;  import betlista.tests.swagger.model.Input; import betlista.tests.swagger.model.Output; import com.wordnik.swagger.annotations.Api; import com.wordnik.swagger.annotations.ApiOperation;  @Api(value = "second", position = 2) public class RestServiceSecond {      @ApiOperation(value = "foo2 operation", httpMethod = "POST", position = 1)     public void foo2(Input input) {      }      @ApiOperation(value = "bar2 operation", response = Output.class, httpMethod = "GET", position = 2)     public Output bar2() {         return null;     }  } 

Input

package betlista.tests.swagger.model;  import com.wordnik.swagger.annotations.ApiModel; import com.wordnik.swagger.annotations.ApiModelProperty;  @ApiModel public class Input {      @ApiModelProperty(dataType = "string", allowableValues = "M, T", value = "description", notes = "notes")     public Day day;  } 

Day

package betlista.tests.swagger.model;  public enum Day {      Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday;  } 

Output

package betlista.tests.swagger.model;  import com.wordnik.swagger.annotations.ApiModel;  @ApiModel(value = "Output") public class Output {      @ApiModelProperty     String field;  } 

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">     <modelVersion>4.0.0</modelVersion>      <groupId>betlista</groupId>     <artifactId>tests-swagger</artifactId>     <version>0.0.1-SNAPSHOT</version>      <dependencies>         <!-- generate REST documentation -->         <dependency>             <groupId>com.wordnik</groupId>             <artifactId>swagger-jaxrs_2.10</artifactId>             <version>1.3.2</version>         </dependency>      </dependencies>      <build>         <plugins>             <plugin>                 <groupId>com.github.kongchen</groupId>                 <artifactId>swagger-maven-plugin</artifactId>                 <version>2.0</version>                 <configuration>                     <apiSources>                         <apiSource>                             <locations>betlista.tests.swagger;betlista.tests.swagger.model</locations>                             <apiVersion>1.0.0</apiVersion>                             <basePath>http://localhost:port/rest</basePath>                             <outputTemplate>${basedir}/strapdown.html.mustache</outputTemplate>                             <outputPath>${basedir}/target/generated/strapdown.html</outputPath>                             <swaggerDirectory>${basedir}/target/generated/apidocs</swaggerDirectory>                             <useOutputFlatStructure>false</useOutputFlatStructure>                         </apiSource>                     </apiSources>                 </configuration>                 <executions>                     <execution>                         <phase>compile</phase>                         <goals>                             <goal>generate</goal>                         </goals>                     </execution>                 </executions>             </plugin>         </plugins>     </build> </project> 

You can see the result here.

There is a lot of problems in HTML output I see (missing Output description, wrong URLs, description is used for notes), but the one I do not know how to overcome is enum usage.

In tests-swagger\target\generated\apidocs\first.json should be (I think)

  "models" : {     "Input" : {       "id" : "Input",       "description" : "",       "properties" : {         "day" : {           "type" : "string",           "enum" : [ "M", " T" ]         }       }     }   } 

but there is

  "models" : {     "Input" : {       "id" : "Input",       "description" : "",       "properties" : {         "day" : {           "$ref" : "Day",           "enum" : [ "M", " T" ]         }       }     }   } 

and the $ref is a problem I think...

Any idea?

Answer 1

In case of swagger-maven-plugin 3.1.0 this might be a minimal documentation:

@ApiModel public class Input {     @ApiModelProperty     public Day day; }  @ApiModel public enum Day {     Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday; } 

Then this is the generated json model:

"definitions" : {   "Input" : {     "type" : "object",     "properties" : {       "day" : {         "type" : "string",         "enum" : [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ]       }     }   } } 

And this is how the model is presented in the SwaggerUI:

Input { day (string, optional) = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'] }