web-dev-qa-db-fra.com

Enum en fanfaron

Je me demande comment documenter les enums en swagger.

Selon JavaDoc

Le type de données. Voir la documentation pour les types de données pris en charge. Si le type de données est un objet personnalisé, définissez son nom ou rien. Dans le cas d'une énumération, utilisez 'string' et allowableValues ​​pour les constantes enum.

Mais je n'ai pas trouvé de bon exemple en Java pour l'utiliser, la spécification est ici .

Java

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

}

Deuxième 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;
    }

}

Contribution

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;

}

Journée

package betlista.tests.swagger.model;

public enum Day {

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

}

Sortie

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>

Vous pouvez voir le résultat ici .

Je constate que la sortie HTML présente de nombreux problèmes (description de sortie manquante, URL erronées, description utilisée pour les notes), mais celle que je ne sais pas comment résoudre est l’utilisation enum.

Dans tests-swagger\target\generated\apidocs\first.json devrait être (je pense)

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

mais il y a

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

et le $ref est un problème je pense ...

Une idée?

javaswaggerswagger-maven-plugin
20
Betlista

Dans le cas de swagger-maven-plugin 3.1.0, ceci pourrait être une documentation minimale:

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

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

Ensuite, voici le modèle JSON généré:

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

Et voici comment le modèle est présenté dans le SwaggerUI:

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

Selon le document que vous avez indiqué:

Le type de données. Voir la documentation pour les types de données pris en charge. Si le type de données est un objet personnalisé, définissez son nom ou rien. En cas d'enum, utilisez 'string' et allowableValues ​​pour les constantes enum

Je pense que vous devriez ajouter les valeurs enum manuellement:

@ApiModel
public class Input {

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

Solution personnalisée Springfox Plugin:

swagger.io recommande: "Si vous devez spécifier des descriptions pour les éléments enum, vous pouvez le faire dans la description du paramètre ou de la propriété"

J'ai implémenté cette recommandation sur la base d'une annotation propriétaire @ApiEnum. La bibliothèque est disponible ici: https://github.com/hoereth/springfox-enum-plugin

3
Mick

Vous pouvez utiliser responseContainer avec votre annotation @ApiOperation:

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