webentwicklung-frage-antwort-db.com.de

Enum in Prahlerei

Ich frage mich, wie man Enummen in Prahlerei dokumentiert.

Nach JavaDoc

Der Datentyp. In der Dokumentation finden Sie die unterstützten Datentypen. Wenn der Datentyp ein benutzerdefiniertes Objekt ist, legen Sie den Namen oder nichts fest. Im Falle einer Enumeration verwenden Sie 'string' und allowableValues ​​für die Enumenkonstanten.

Aber ich habe kein gutes Java-Beispiel gefunden, wie man es wirklich benutzt, Spezifikation ist hier .

Java

Erster 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;
    }

}

Zweiter 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;
    }

}

Eingang

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;

}

Tag

package betlista.tests.swagger.model;

public enum Day {

    Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday;

}

Ausgabe

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>

Sie können das Ergebnis hier sehen.

Ich sehe eine Menge Probleme in der HTML-Ausgabe (fehlende Beschreibung der Ausgabe, falsche URLs, Beschreibung wird für Notizen verwendet), aber die, die ich nicht überwinden kann, ist die Verwendung der Enummen.

In tests-swagger\target\generated\apidocs\first.json sollte sein (denke ich)

  "models" : {
    "Input" : {
      "id" : "Input",
      "description" : "",
      "properties" : {
        "day" : {
          "type" : "string",
          "enum" : [ "M", " T" ]
        }
      }
    }
  }

aber da ist

  "models" : {
    "Input" : {
      "id" : "Input",
      "description" : "",
      "properties" : {
        "day" : {
          "$ref" : "Day",
          "enum" : [ "M", " T" ]
        }
      }
    }
  }

und der $ref ist ein problem, denke ich ...

Irgendeine Idee?

20
Betlista

Im Falle von swagger-maven-plugin 3.1.0 kann dies eine minimale Dokumentation sein:

@ApiModel
public class Input {
    @ApiModelProperty
    public Day day;
}

@ApiModel
public enum Day {
    Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday;
}

Dann ist dies das generierte Json-Modell:

"definitions" : {
  "Input" : {
    "type" : "object",
    "properties" : {
      "day" : {
        "type" : "string",
        "enum" : [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ]
      }
    }
  }
}

Und so präsentiert sich das Modell in der SwaggerUI:

Input {
day (string, optional) = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
}
11
user3078523

Laut dem Dokument, auf das Sie hingewiesen haben:

Der Datentyp. In der Dokumentation finden Sie die unterstützten Datentypen. Wenn der Datentyp ein benutzerdefiniertes Objekt ist, legen Sie den Namen oder nichts fest. Im Falle einer Enumeration benutze 'string' und allowableValues ​​für die Enumenkonstanten.

Ich denke, Sie sollten die Aufzählungswerte manuell hinzufügen:

@ApiModel
public class Input {

    @ApiModelProperty(dataType = "string", allowableValues = "Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", value = "description", notes = "notes")
    public Day day;
}
5
kongyk

Benutzerdefinierte Springfox Plugin-Lösung:

swagger.io empfiehlt: "Wenn Sie Beschreibungen für Aufzählungselemente angeben müssen, können Sie dies in der Beschreibung des Parameters oder der Eigenschaft tun"

Ich habe diese Empfehlung basierend auf einer proprietären @ApiEnum-Annotation implementiert. Die Bibliothek ist hier verfügbar: https://github.com/hoereth/springfox-enum-plugin

3
Mick

In der OpenApi-Version Swagger 2.x müssen Sie die hier beschriebenen neuen Anmerkungen verwenden: 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;
   ...
   ...

Daraus ergibt sich etwa Folgendes: enter image description here

2
max

Sie können responseContainer mit Ihrer @ApiOperation-Anmerkung verwenden:

@ApiOperation(value = "Brief description of your operation.", response = YourEnum.class, responseContainer = "List")
0
rodrigocprates