33

我想知道如何在招摇中记录枚举。

根据JavaDoc

数据类型。有关支持的数据类型,请参阅文档。如果数据类型是自定义对象,请设置它的名称,或者不设置任何内容。在枚举的情况下,使用 'string' 和 allowableValues 作为枚举常量。

但是我没有找到一些好的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

<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>

你可以在这里看到结果。

我看到的 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是一个问题......

任何的想法?

4

6 回答 6

22

如果是 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']
}
于 2015-07-17T12:45:28.160 回答
12

根据您指出的文档:

数据类型。有关支持的数据类型,请参阅文档。如果数据类型是自定义对象,请设置它的名称,或者不设置任何内容。在枚举的情况下,使用 'string' 和 allowableValues 作为枚举常量。

我认为您应该手动添加枚举值:

@ApiModel
public class Input {

    @ApiModelProperty(dataType = "string", allowableValues = "Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", value = "description", notes = "notes")
    public Day day;
}
于 2014-09-03T04:45:37.930 回答
6

自定义 Springfox 插件解决方案:

swagger.io 建议:“如果需要为枚举项指定描述,可以在参数或属性的描述中进行”

我根据专有的@ApiEnum 注释实现了这个建议。该库可在此处获得:https ://github.com/hoereth/springfox-enum-plugin

于 2018-11-06T08:03:55.797 回答
4

在 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;
   ...
   ...

导致这样的事情: 在此处输入图像描述

于 2019-07-12T12:00:29.233 回答
1

您可以将 responseContainer 与您的 @ApiOperation 注释一起使用:

@ApiOperation(value = "Brief description of your operation.", response = YourEnum.class, responseContainer = "List")
于 2017-04-19T14:16:10.897 回答
0

感谢您的帮助。

我在我的代码中已经习惯了这种类型。

private String date;
@ApiModelProperty(dataType = "string", allowableValues = "FirstValue,   SecondValue", value = "description", notes = "notes")
private CarrierType carrierName;


public enum CarrierType {
    FirstValue,
    SecondValue
}

它对我来说很好。

于 2016-06-22T07:44:03.313 回答