x-examples for post examples

[fehguy]

In the 1.2 swagger-spec, we had support for example post bodies. This was controversially removed in 2.0 as we expected the model schema to be enough for examples. That proved to be a mistake as the values, even in the same schema, might need to vary between requests.

To work around in the mean time, and provide backwards support, we added an x-examples support in the post body:

{
  "in" : "body",
  "name" : "body",
  "description" : "test",
  "required" : false,
  "schema" : {
    "type" : "array",
    "items" : {
      "type" : "string"
    }
  },
  "x-examples" : {
    "application/json" : "[\"a\",\"b\"]"
  }
}

Note the x-examples may be a string or an object. The UI should determine if it can be parsed as an object based on the content-type in the key.

During the transition to rendering on the UI side, this was lost.

@bodnia can you see about adding it back?

[bodnia]

In specification I found following about vendor extensions:

Allows extensions to the Swagger Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Unfortunately this doesn't look clear. @fehguy @webron could you please give me more background on vendor extensions? Thank you in advance!

[webron]

Almost all objects in the spec allow you to define vendor extensions to them, including parameters - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#patterned-fields-2.

The value of the vendor extensions is undefined and can be any valid JSON - based on the user preferences.

A few months ago @fehguy added support for x-examples (for body parameters, x-example for others) to allow users to provide examples for requests, a feature that's missing from the spec. If you try the sample above, you'll see that the text-box rendering of that is [Object object] or something similar instead of the actual body sample that is provided in x-examples as it should.

Keep in mind that x-examples is a map between a mime type and a sample, with the option of default as a mime type for a general purpose documentation (that can be used if the requested mime type doesn't exist in the example).

[mkrufky]

The following generic spec correctly pre-populates my POST body examples, but doesn't actually pre-populate the textbox for submission under the latest swagger UI. It took me some time to figure this out, but it works. I haven't yet tried x-examples but this has been working fine. If the user clicks on the Example Value, the data gets copied over to the box :

paths:
  /endpoint:
    post:
      parameters:
        - name: postBodyObj
          in: body
          schema:
            $ref: '#/definitions/postBodyObj'

...

definitions:
  postBodyObj:
    type: object
    default:
      postBodyObj: [ 1,2,3 ]
    properties:
      postBodyObj:
        type: array
        items: number

I felt the need to share this here because the issue description seems to imply that there is no such feature in the latest Swagger UI. Well, it works for me :-)

It would be better if the user didn't have to click the Example Value in order to populate the textbox, but maybe this illustrates that the required fix may not be as much work as it seems.

[webron]

@mkrufky - fwiw, that's not a valid array definition.

definitions:
  postBodyObj:
    type: object
    default:
      postBodyObj: [ 1,2,3 ]
    properties:
      postBodyObj:
        type: array
        items: 
          type: number

[mkrufky]

Apparently it's very forgiving :-) The validator does complain about it, but the functionality seems to work regardless:

{"messages":["attribute definitions.postBodyObj.default is not of type `string`"],"schemaValidationMessages":[{"level":"error","domain":"validation","keyword":"anyOf","message":"instance failed to match at least one required schema among 2","schema":{"loadingURI":"http://swagger.io/v2/schema.json#","pointer":"/definitions/schema/properties/items"},"instance":{"pointer":"/definitions/postBodyObj/properties/postBodyObj/items"}}]}

Despite failing the validator, the functionality seems to work.

I have a different POST endpoint using this instead for a default example block:

definitions:
  postBodyObj:
    type: object
    default:
      postBodyObj: "ABC,DEF"
    properties:
      postBodyObj:
        type: string

The functionality seems to work properly even though the validator complains with a similar error as the other endpoint:

{"messages":["attribute definitions.postBodyObj.default is not of type string"]}

After fixing the array in my original snippet, the validator gives the same error as above ^ while all seems to be functioning properly.

I'd hate to deter too much from the topic of this issue, but again, I only bring it up because it seems to work regardless of what the validator says.

[juan-quiver]

This doesn't seem to be implemented as of v 2.1.5, using x-examples is parsed as a vendor extension but it has no effect on swagger-ui, I can't see any of my x-example values. Check this sample definition:

swagger: '2.0'
info:
  version: 1.0.0
  title: Sample for testing x-examples
basePath: /sample
produces:
  - application/json

paths:
  /test:
    get:
      summary: Example operation
      description: desc
      parameters:
        - name: user
          in: body
          description: the body
          required: true
          schema:
            properties:
              id:
                type: string
          x-examples:
            application/json: 
              id: 123
      responses:
        200:
          description: response test

[jenniferwang2000]

I also tried to add request body example by using "x-examples", it didn't show up in UI, either. I just wonder how to add request body example. Anyone can help with this?

[aivans]

I would like to document the rate limits for each operation.
I would like to define something like this:

 "get": {
                "x-ratelimit-allowed": "100",

It would be nice if Swagger UI can show this info in a friendly format.

[tedepstein]

We're seeing that Swagger-UI does show the value of x-example as the default on non-body parameters.

But it doesn't show the value of x-examples/[media-type].

paths:
  /pet:
    patch:
      summary: Partial update
      description: Update pet
      parameters:
       - name: authorized-by
         in: query
         required: true
         type: string
         # This header param shows up as the default in the 
         # 'try it out' panel.
         x-example:
          "Stewart the Data Steward"
       - name: body
         in: body
         required: true
         schema:
           $ref: "#/definitions/Pet"
         # This seems to have no effect. 
         x-examples: 
          application/json : |
            {
              "id" : 11234,
              "name" : "Chloe",
              "tag" : "dog"
            }  
      responses:
        '200':
          description: OK
          schema:
            $ref: "#/definitions/Pet"

Was x-examples ever implemented for body params?

[webron]

I think it only works for media-type default. Can you try that?

[tedepstein]

@webron , yes, you're right. It works with default:

swagger: "2.0"
info:
  version: 1.0.0
  title: Swagger Petstore
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /pet:
    patch:
      summary: Partial update
      description: Update pet
      parameters:
       - name: authorized-by
         in: query
         required: true
         type: string
         x-example:
          "Stewart the Data Steward"
       - name: body
         in: body
         required: true
         schema:
           $ref: "#/definitions/Pet"
         x-examples: 
          default : |
            {
              "id" : 11234,
              "name" : "Chloe",
              "tag" : "dog"
            }  
      responses:
        '200':
          description: OK
          schema:
            $ref: "#/definitions/Pet"

definitions:
  Pet:
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      tag:
        type: string

Thanks for that tip.

Other limitations:

• Note that in my example, the value is a string,not an object. The pipe character after default : does this. If I left it as an object, I'd run into this issue with Swagger-Parser, addressed here, but not in the release build yet. This isn't an issue with Swagger-UI, but my toolchain relies on swagger-parser. The string value is a workaround.
• The specified x-examples/default value appears as the default value in Swagger-UI, but it doesn't change the "Model Schema" shown in the Data Type column:
  

[petermorlion]

@fehguy You mention "In the 1.2 swagger-spec, we had support for example post bodies", can you point me towards this?

Unfortunately, I'm working on a NodeJS application that works with Swagger 1.2 and generates documentation from code. It is my understanding you're currently advocating the other way around. But that would probably take me too far, so I'm continueing with Swagger 1.2, and actually converting the resulting spec to Swagger 2.0 on the fly. But I would like to add example jsons to my requests and responses. You mention it is possible, but I can't seem to find any reference to it in the Swagger 1.2 specification.

[ShayanBE]

My solution and it worked fine for me:
Inside my requestClass i added @ApiModelProperty like this:

@ApiModelProperty (value = "id", example = "1234")
@QueryParam("id")
 private String id;