java - swagger2 - swagger response model annotations

¿Cómo puedo establecer una descripción y un ejemplo en Swagger con las anotaciones de Swagger?

Question

Estoy creando un Api REST utilizando Spring boot, y estoy generando automáticamente la documentación de Swagger en los controladores que usan Swagger Codegen. Sin embargo, no puedo establecer una descripción y un ejemplo para un parámetro de tipo Cadena en una solicitud POST. Aquí está mi código:

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

La propiedad de ejemplo de @ApiParam ha sido insertada manualmente por mí, porque el código estaba ignorando esa parte del yaml (esa es otra pregunta: ¿por qué el editor ignora la parte del ejemplo?). Aquí es parte del 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
        }

Y, finalmente, esto es lo que muestra swagger:

Finalmente, las dependencias usadas en build.gradle son las siguientes:

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

Entonces, la pregunta es: ¿Alguien sabe cómo puedo configurar la descripción y un ejemplo de un parámetro de cuerpo utilizando anotaciones de arrogancia?

EDITAR

Logré cambiar la descripción usando @ApiImplicitParam en lugar de @ApiParam, pero aún falta el ejemplo:

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

Answer 1

En realidad, el documento java para la propiedad de example de la anotación @ApiParam establece que esto debe usarse exclusivamente para parámetros no corporales. Donde la propiedad de examples puede ser usada para los parámetros del cuerpo.

He probado esta anotación

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

que dio lugar a la siguiente arrogancia que se generará para el método correspondiente:

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

Sin embargo, este valor no parece ser recogido por swagger-ui. Probé la versión 2.2.10 y la última versión 3.17.4, pero ninguna de las dos utilizaba la propiedad x-examples de swagger.

Hay algunas referencias para x-example (la que se usa para parámetros no corporales) en el código de swagger-ui pero no coinciden con x-examples . Es decir, esto no parece estar respaldado por swagger-ui en este momento.

Si realmente necesita que estos valores de ejemplo estén presentes, su mejor opción actualmente parece ser cambiar la firma de su método y usar un tipo de dominio dedicado para el parámetro del cuerpo. Como se indica en los comentarios, swagger recogerá automáticamente la estructura del tipo de dominio e imprimirá información interesante en swagger-ui:

Answer 2

Has intentado lo siguiente ?

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

Que tengas un buen día

Answer 3

Tengo un problema similar con la generación de ejemplos para objetos de cuerpo: la anotación @Example y @ExampleProperty simplemente no funciona sin motivo alguno en swagger 1.5.x. (Yo uso 1.5.16)

Mi solución actual es:
use @ApiParam(example="...") para objetos no corporales , por ejemplo:

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

para los objetos del cuerpo , cree una nueva clase y anote los campos con @ApiModelProperty(value = " ", example = " ") , por ejemplo:

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