恩惠在招摇
我想知道如何以昂首阔步的方式记录枚举。
根据JavaDoc
dataType。 有关支持的数据类型,请参阅文档。 如果数据类型是自定义对象,请设置其名称,或者不设置任何名称。 在枚举的情况下,使用’string’和allowableValues作为枚举常量。
但我没有找到一些好的Java示例如何真正使用它,规范在这里 。
Java的
第一次服务
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; } }
第二次服务
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; } }
输入
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; }
天
package betlista.tests.swagger.model; public enum Day { Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday; }
产量
package betlista.tests.swagger.model; import com.wordnik.swagger.annotations.ApiModel; @ApiModel(value = "Output") public class Output { @ApiModelProperty String field; }
的pom.xml
4.0.0 betlista tests-swagger 0.0.1-SNAPSHOT com.wordnik swagger-jaxrs_2.10 1.3.2 com.github.kongchen swagger-maven-plugin 2.0 betlista.tests.swagger;betlista.tests.swagger.model 1.0.0 http://localhost:port/rest ${basedir}/strapdown.html.mustache ${basedir}/target/generated/strapdown.html ${basedir}/target/generated/apidocs false compile generate
你可以在这里看到结果。
我看到HTML输出中存在很多问题(缺少输出描述,错误的URL,描述用于注释),但我不知道如何克服的是枚举用法。
在tests-swagger\target\generated\apidocs\first.json
应该是(我认为)
"models" : { "Input" : { "id" : "Input", "description" : "", "properties" : { "day" : { "type" : "string", "enum" : [ "M", " T" ] } } } }
但是还有
"models" : { "Input" : { "id" : "Input", "description" : "", "properties" : { "day" : { "$ref" : "Day", "enum" : [ "M", " T" ] } } } }
而且我认为$ref
是个问题……
任何想法?
对于swagger-maven-plugin 3.1.0,这可能是一个最小的文档:
@ApiModel public class Input { @ApiModelProperty public Day day; } @ApiModel public enum Day { Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday; }
然后这是生成的json模型:
"definitions" : { "Input" : { "type" : "object", "properties" : { "day" : { "type" : "string", "enum" : [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] } } } }
这就是SwaggerUI中模型的呈现方式:
Input { day (string, optional) = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'] }
根据你指出的文件:
dataType。 有关支持的数据类型,请参阅文档。 如果数据类型是自定义对象,请设置其名称,或者不设置任何名称。 在枚举的情况下,使用’string’和allowableValues作为枚举常量。
我认为你应该手动添加枚举值:
@ApiModel public class Input { @ApiModelProperty(dataType = "string", allowableValues = "Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", value = "description", notes = "notes") public Day day; }
您可以将responseContainer与@ApiOperation注释一起使用:
@ApiOperation(value = "Brief description of your operation.", response = YourEnum.class, responseContainer = "List")
谢谢你的帮助。
我在我的代码中习惯了这种类型。
private String date; @ApiModelProperty(dataType = "string", allowableValues = "FirstValue, SecondValue", value = "description", notes = "notes") private CarrierType carrierName; public enum CarrierType { FirstValue, SecondValue }
它对我来说很好。