Wie kann ich eine Beschreibung und ein Beispiel in Swagger mit Swagger-Anmerkungen festlegen?

Ich habe ein ähnliches Problem beim Generieren von Beispielen für Körperobjekte - Annotation @Example Und @ExampleProperty Funktionieren in swagger 1.5.x einfach nicht ohne Grund. (Ich benutze 1.5.16)

Meine aktuelle Lösung ist:
Verwenden Sie @ApiParam(example="...") für Nichtkörperobjekte, z.

public void post(@PathParam("userId") @ApiParam(value = "userId", example = "4100003") Integer userId) {}

für body Objekte werden neue Klassen erstellt und Felder mit @ApiModelProperty(value = " ", example = " ") beschriftet, z.

@ApiModel(subTypes = {BalanceUpdate.class, UserMessage.class})
class PushRequest {
    @ApiModelProperty(value = "status", example = "Push")
    private final String status;;
}

Eigentlich das Java doc für die example -Eigenschaft des @ApiParam annotation gibt an, dass dies ausschließlich für Nicht-Body-Parameter verwendet werden soll. Dabei kann die Eigenschaft examples für Körperparameter verwendet werden.

Ich habe diese Anmerkung getestet

@ApiParam(
  value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.",
  examples = @Example(value = 
    @ExampleProperty(
      mediaType = MediaType.APPLICATION_JSON,
      value = "{foo: whatever, bar: whatever2}"
    )
  )
)

was dazu führte, dass für die entsprechende Methode folgende Prahlerei generiert wurde:

/transaction:
  post:
  ...
    parameters:
    ...
    - in: "body"
      name: "body"
      description: "A JSON value representing a transaction. An example of the expected\
        \ schema can be found down here. The fields marked with an * means that\
        \ they are required."
      required: false
      schema:
        type: "string"  
      x-examples:
        application/json: "{foo: whatever, bar: whatever2}"

Dieser Wert scheint jedoch nicht von swagger-ui erfasst zu werden. Ich habe Version 2.2.10 und die neueste Version 3.17.4 ausprobiert, aber in keiner der Versionen wurde x-examples Eigentum des Prahlers.

Es gibt einige Referenzen für x-example (der für Nicht-Körper-Parameter verwendete) im Code von swagger-ui , aber keine Übereinstimmung für x-examples. Das heißt, dies scheint momentan nicht von swagger-ui unterstützt zu werden.

Wenn Sie diese Beispielwerte wirklich benötigen, besteht Ihre beste Möglichkeit derzeit darin, die Signatur Ihrer Methode zu ändern und einen dedizierten Domänentyp für den body-Parameter zu verwenden. Wie bereits in den Kommentaren erwähnt, erkennt swagger automatisch die Struktur des Domain-Typs und gibt einige nützliche Informationen in swagger-ui aus:

Haben Sie folgendes versucht?

@ApiModelProperty(
    value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.",
    example = "{foo: whatever, bar: whatever2}")

Einen schönen Tag noch

Wenn Sie swagger 2.9.2 verwenden, funktionieren die Beispiele dort nicht. Diese Anmerkungen werden ignoriert

protected Map<String, Response> mapResponseMessages(Set<ResponseMessage> from) {
  Map<String, Response> responses = newTreeMap();
  for (ResponseMessage responseMessage : from) {
    Property responseProperty;
    ModelReference modelRef = responseMessage.getResponseModel();
    responseProperty = modelRefToProperty(modelRef);
    Response response = new Response()
        .description(responseMessage.getMessage())
        .schema(responseProperty);
    **response.setExamples(Maps.<String, Object>newHashMap());**
    response.setHeaders(transformEntries(responseMessage.getHeaders(), toPropertyEntry()));
    Map<String, Object> extensions = new VendorExtensionsMapper()
        .mapExtensions(responseMessage.getVendorExtensions());
    response.getVendorExtensions().putAll(extensions);
    responses.put(String.valueOf(responseMessage.getCode()), response);
  }
  return responses;
}

Versuchen Sie es mit swagger 3.0.0-Snapshot. Sie müssen Maven-Abhängigkeiten wie folgt ändern:

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-webmvc</artifactId>
            <version>3.0.0-SNAPSHOT</version>
        </dependency>

und ändern Sie die Anmerkung in Ihrer Swagger-Konfigurationsdatei in: @ EnableSwagger2WebMvc