web-dev-qa-db-fra.com

Comment définir une description et un exemple dans les annotations Swagger with Swagger?

Je crée un REST Api à l'aide de Spring Boot et génère automatiquement la documentation swagger dans les contrôleurs à l'aide de swagger codegen. Toutefois, je ne peux pas définir de description ni d'exemple pour un paramètre de type String in une demande POST. Voici le code mi:

import io.swagger.annotations.*;

@Api(value = "transaction", tags = {"transaction"})
@FunctionalInterface
public interface ITransactionsApi {
    @ApiOperation(value = "Places a new transaction on the system.", notes = "Creates a new transaction in the system. See the schema of the Transaction parameter for more information ", tags={ "transaction", })
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Another transaction with the same messageId already exists in the system. No transaction was created."),
        @ApiResponse(code = 201, message = "The transaction has been correctly created in the system"),
        @ApiResponse(code = 400, message = "The transaction schema is invalid and therefore the transaction has not been created.", response = String.class),
        @ApiResponse(code = 415, message = "The content type is unsupported"),
        @ApiResponse(code = 500, message = "An unexpected error has occurred. The error has been logged and is being investigated.") })

    @RequestMapping(value = "/transaction",
        produces = { "text/plain" },
        consumes = { "application/json" },
        method = RequestMethod.POST)
    ResponseEntity<Void> createTransaction(
        @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." ,
            example = "{foo: whatever, bar: whatever2}")
        @Valid @RequestBody String kambiTransaction) throws InvalidTransactionException;
}

L'exemple de propriété de @ApiParam a été inséré manuellement par moi-même, car le codegen ignorait cette partie du yaml (autre question: pourquoi l'éditeur ignore-t-il la partie d'exemple?). Voici une partie du yaml:

paths:
  /transaction:
    post:
      tags:
        - transaction
      summary: Place a new transaction on the system.
      description: >
        Creates a new transaction in the system. See the schema of the Transaction parameter
        for more information
      operationId: createTransaction
      parameters:
        - $ref: '#/parameters/transaction'
      consumes:
        - application/json
      produces:
        - text/plain
      responses:
        '200':
          description: Another transaction with the same messageId already exists in the system. No transaction was created.
        '201':
          description: The transaction has been correctly created in the system
        '400':
          description: The transaction schema is invalid and therefore the transaction has not been created.
          schema:
            type: string
            description: error message explaining why the request is a bad request.
        '415':
          description: The content type is unsupported
        '500':
          $ref: '#/responses/Standard500ErrorResponse'

parameters:
  transaction:
    name: kambiTransaction
    in: body
    required: true
    description: A JSON value representing a kambi transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.
    schema:
      type: string
      example:
        {
          foo*: whatever,
          bar: whatever2
        }

Et enfin, voici ce que swagger montre:

enter image description here

Enfin, les dépendances utilisées dans build.gradle sont les suivantes:

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'

La question est donc la suivante: Quelqu'un sait-il comment définir la description et un exemple de paramètre de corps à l'aide d'annotations swagger?

[~ # ~] éditer [~ # ~]

J'ai réussi à changer la description en utilisant @ApiImplicitParam au lieu de @ApiParam, mais l'exemple est toujours manquant:

@ApiImplicitParams({
    @ApiImplicitParam(
        name = "kambiTransaction",
        value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with * means that they are required. See the schema of KambiTransaction for more information.",
        required = true,
        dataType = "String",
        paramType = "body",
        examples = @Example(value = {@ExampleProperty(mediaType = "application/json", value = "{foo: whatever, bar: whatever2}")}))})
javaspringswaggerswagger-codegen
29
DarthRoman

J'ai un problème similaire avec la génération d'exemples d'objets body - l'annotation @Example Et @ExampleProperty Ne fonctionne tout simplement pas sans raison dans swagger 1.5.x. (J'utilise 1.5.16)

Ma solution actuelle est:
utilise @ApiParam(example="...") pour objets autres que des corps, par exemple:

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

for body les objets créent une nouvelle classe et annotent des champs avec @ApiModelProperty(value = " ", example = " "), par exemple:

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

En réalité, la Java doc de la propriété example de l'annotation @ApiParam Indique que cette propriété doit exclusivement être utilisée pour des paramètres autres que ceux du corps. Où examples peut être utilisée pour les paramètres de corps.

J'ai testé cette annotation

@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}"
    )
  )
)

ce qui a généré le swagger suivant pour la méthode correspondante:

/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}"

Cependant, cette valeur ne semble pas être prise en compte par swagger-ui. J'ai essayé la version 2.2.10 et la dernière version 3.17.4, mais aucune des deux versions n'utilisait la propriété x-examples Du swagger.

Il y a quelques références pour x-example (Celle utilisée pour les paramètres autres que du corps) dans code de swagger-ui mais aucune correspondance pour x-examples. C’est que cela ne semble pas être pris en charge par swagger-ui pour le moment.

Si vous avez réellement besoin de la présence de cet exemple, la meilleure solution semble actuellement consister à modifier la signature de votre méthode et à utiliser un type de domaine dédié pour le paramètre body. Comme indiqué dans les commentaires déjà, swagger récupérera automatiquement la structure du type de domaine et imprimera quelques informations de Nice dans swagger-ui:

Swagger-UI 2.2.10 with domain type info

2
dpr

Avez-vous essayé le suivant?

@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}")

Bonne journée

1
E. Bavoux

Si vous utilisez swagger 2.9.2, les exemples ne fonctionnent pas. Ces annotations sont ignorées

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

Essayez d'utiliser swagger 3.0.0-Snapshot. Vous devez changer les dépendances maven comme ceci:

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

et remplacez les annotations de votre fichier de configuration Swagger par ceci: @ EnableSwagger2WebMvc

0
Евгений Коптюбенко