He estado tratando de agregar ejemplos a mi API Swagger de acuerdo con el documentos oficiales (ver el último bloque de código deRequest y ejemplos del cuerpo de respuesta) pero no parece funcionar como se esperaba.

Considerando el siguiente ejemplo mínimo:

swagger: "2.0"
info:
  description: Desc
  version: "1"
  title: Title
paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          content:
            application/json:
              schema:
                $ref: "#/definitions/StatusMessage"
              examples:
                Success without message:
                  value:
                    code: "00000"
                Success with message:
                  value:
                    code: "00000"
                    message: "All right"
definitions:
  StatusMessage:
    type: object
    description: Response with code and optional message
    properties:
      code:
        type: string
      message:
        type: string
    required:
    - code

Quiero proporcionar respuestas de muestra, una con la propiedad opcionalmessage presente y el otro sin. Sin embargo, el archivo YAML mencionado anteriormente arroja resultados incorrectos en la Clase API generada:

@ApiOperation(value = "", nickname = "stuffPost", notes = "", tags={  })
@ApiResponses(value = { 
    @ApiResponse(code = 201, message = "It worked") })
@RequestMapping(value = "/stuff",
    method = RequestMethod.POST)
default ResponseEntity<Void> stuffPost() { /*default implementation*/ }

Losproduces@ propiedad no está presente y el tipo de retorno es incorrecto! Además, esto no se compila en elSwagger Editor: elresponses propiedadshould NOT have additional properties.

Lo he cambiado para obtener un ejemplo "válido" en el Editor Swagger, pero el código generado también es incorrecto. Vea abajo

paths:
  /stuff:
    post:
      produces:
      - application/json
      responses:
        201:
          description: It worked
          schema:
            $ref: "#/definitions/StatusMessage"
          examples:
            Success without message:
              code: "00000"
            Success with message:
              code: "00000"
              message: "All right"

El método generado es:

@ApiOperation(value = "", nickname = "stuffPost", notes = "", response = StatusMessage.class, tags={  })
@ApiResponses(value = { 
    @ApiResponse(code = 201, message = "It worked", response = StatusMessage.class) })
@RequestMapping(value = "/stuff",
    produces = { "application/json", "Success without message", "Success with message" }, 
    method = RequestMethod.POST)
default ResponseEntity<StatusMessage> stuffPost() { /*default implementation*/ }

Esta vez, laproduces la propiedad está ahí pero completamente apagada!

¿Cómo puedo hacer que esto funcione? Funciona si uso la segunda versión conapplication/json como clave para el título del ejemplo, pero eso me impide agregar más ejemplos debido a la clave duplicada.