Java 大摇大摆的枚举
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/23936140/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Enum in swagger
提问by Betlista
I'm wondering how to document enums in swagger.
我想知道如何在 swagger 中记录枚举。
According to JavaDoc
根据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.
数据类型。请参阅支持的数据类型的文档。如果数据类型是自定义对象，则设置它的名称，或者什么也不设置。在枚举的情况下，使用 'string' 和 allowedValues 作为枚举常量。
But I didn't find some good Java example how to really use it, specification is here.
但是我没有找到一些很好的 Java 示例如何真正使用它，规范在这里。
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
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.
我看到HTML输出有很多问题（缺少输出描述，错误的URL，描述用于注释），但我不知道如何克服枚举用法。
In tests-swagger\target\generated\apidocs\first.jsonshould be (I think)
在tests-swagger\target\generated\apidocs\first.json应该是（我认为）
"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 $refis a problem I think...
这$ref是我认为的一个问题......
Any idea?
任何的想法？
采纳答案by user3078523
In case of swagger-maven-plugin 3.1.0 this might be a minimal documentation:
在 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;
}
Then this is the generated json model:
那么这是生成的json模型：
"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:
这就是模型在 SwaggerUI 中的呈现方式：
Input {
day (string, optional) = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
}
回答by kongyk
According to the doc you pointed:
根据您指出的文档：
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.
数据类型。请参阅支持的数据类型的文档。如果数据类型是自定义对象，则设置它的名称，或者什么也不设置。在枚举的情况下，使用 'string' 和 allowedValues 作为枚举常量。
I think you should add the enum values manually:
我认为您应该手动添加枚举值：
@ApiModel
public class Input {
@ApiModelProperty(dataType = "string", allowableValues = "Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", value = "description", notes = "notes")
public Day day;
}
回答by sadhana
Thanks for this help.
感谢您的帮助。
I have used to this type in my code.
我在我的代码中已经习惯了这种类型。
private String date;
@ApiModelProperty(dataType = "string", allowableValues = "FirstValue, SecondValue", value = "description", notes = "notes")
private CarrierType carrierName;
public enum CarrierType {
FirstValue,
SecondValue
}
It is working fine for me.
它对我来说很好。
回答by rodrigocprates
You may use responseContainer with your @ApiOperation annotation:
您可以将 responseContainer 与 @ApiOperation 注释一起使用：
@ApiOperation(value = "Brief description of your operation.", response = YourEnum.class, responseContainer = "List")
回答by Mick
Custom Springfox Plugin solution:
自定义 Springfox 插件解决方案：
swagger.io recommends: "If you need to specify descriptions for enum items, you can do this in the description of the parameter or property"
swagger.io 建议：“如果您需要为枚举项指定描述，您可以在参数或属性的描述中执行此操作”
I implemented this recommendation based on a proprietary @ApiEnum annotation. The library is available here: https://github.com/hoereth/springfox-enum-plugin
我根据专有的@ApiEnum 注释实施了此建议。该库可在此处获得：https: //github.com/hoereth/springfox-enum-plugin
回答by max
In OpenApi version Swagger 2.x you need to use new annotations described here: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
在 OpenApi 版本 Swagger 2.x 中，您需要使用此处描述的新注释：https: //github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
@Schema(description = "Shuttle shipment action")
public class ShuttleShipmentAction {
@Schema(required = true, description = "Id of a shuttle shipments")
private long id;
@Schema(required = true, description = "Action to be performed on shuttle shipments", allowableValues = { "SEND",
"AUTHORIZE", "REJECT", "FIX_TRAINRUN", "UNFIX_TRAINRUN", "DELETE" })
private String action;
...
...
Resulting in something like this:
结果是这样的：
