java - example - swagger-codegen-maven-plugin
Enumerar en jactancia (5)
En el caso de swagger-maven-plugin 3.1.0, esta podría ser una documentación mínima:
@ApiModel
public class Input {
@ApiModelProperty
public Day day;
}
@ApiModel
public enum Day {
Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday;
}
Entonces este es el modelo json generado:
"definitions" : {
"Input" : {
"type" : "object",
"properties" : {
"day" : {
"type" : "string",
"enum" : [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ]
}
}
}
}
Y así es como se presenta el modelo en SwaggerUI:
Input {
day (string, optional) = [''Monday'', ''Tuesday'', ''Wednesday'', ''Thursday'', ''Friday'', ''Saturday'', ''Sunday'']
}
Me pregunto cómo documentar enumeraciones en swagger.
Según JavaDoc
El tipo de datos. Consulte la documentación para los tipos de datos soportados. Si el tipo de datos es un objeto personalizado, defina su nombre o nada. En el caso de una enumeración, use ''string'' y allowableValues para las constantes enum.
Pero no encontré un buen ejemplo de Java sobre cómo usarlo realmente, la especificación está here .
Java
Primer servicio
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;
}
}
Segundo servicio
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;
}
}
Entrada
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;
}
Día
package betlista.tests.swagger.model;
public enum Day {
Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday;
}
Salida
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>
Puedes ver el resultado here .
Hay muchos problemas en la salida HTML que veo (falta la descripción de la salida, las URL incorrectas, la descripción se usa para las notas), pero la que no sé cómo superar es el uso de la enumeración.
En tests-swagger/target/generated/apidocs/first.json debería ser (creo)
"models" : {
"Input" : {
"id" : "Input",
"description" : "",
"properties" : {
"day" : {
"type" : "string",
"enum" : [ "M", " T" ]
}
}
}
}
pero hay
"models" : {
"Input" : {
"id" : "Input",
"description" : "",
"properties" : {
"day" : {
"$ref" : "Day",
"enum" : [ "M", " T" ]
}
}
}
}
y el $ref es un problema, creo ...
¿Alguna idea?
Gracias por esta ayuda.
He usado este tipo en mi código.
private String date;
@ApiModelProperty(dataType = "string", allowableValues = "FirstValue, SecondValue", value = "description", notes = "notes")
private CarrierType carrierName;
public enum CarrierType {
FirstValue,
SecondValue
}
Está funcionando bien para mí.
Puede usar responseContainer con su anotación @ApiOperation:
@ApiOperation(value = "Brief description of your operation.", response = YourEnum.class, responseContainer = "List")
Según el documento que señalaba:
El tipo de datos. Consulte la documentación para los tipos de datos soportados. Si el tipo de datos es un objeto personalizado, defina su nombre o nada. En el caso de una enumeración, use ''string'' y allowableValues para las constantes enum.
Creo que deberías agregar los valores de enumeración manualmente:
@ApiModel
public class Input {
@ApiModelProperty(dataType = "string", allowableValues = "Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", value = "description", notes = "notes")
public Day day;
}
Solución personalizada del complemento de Springfox:
swagger.io recomienda: "Si necesita especificar descripciones para elementos de enumeración, puede hacerlo en la descripción del parámetro o propiedad"
Implementé esta recomendación basada en una anotación propietaria de @ApiEnum . La biblioteca está disponible aquí: https://github.com/hoereth/springfox-enum-plugin