列挙型をswaggerで文書化する方法を知りたいです。
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は私が思う問題です...
何か案が？