Openapi-specification: The Parameter object needs an "examples" property

[ccleve]

The Response object has a nice {"example": ExampleObject} property which makes it easy to document an operation's response. The Parameter object needs the same thing, particularly when the parameter type is "body". What kind of body is the operation expecting?

[webron]

"body" parameters use schemas to describe their values, and the schema object has an example fields as well - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaExample.

[ccleve]

Good point.

The Response object also has a Schema. Would it make sense to use the example field there instead of the "examples" property in the Response object?

[webron]

Possibly. However, the examples of the responses may also contain headers. Another point is that a request schema example may not be the same as a response schema example. The example field in the schema itself is intended for usage mostly as a request parameter.

[JD557]

What about parameters that are not in the "body"?

While those are simpler, it can be useful to be able to add examples to every required field (eg. to automatically generate curl examples).

[webron]

@JD557 - While I understand the use case, it doesn't serve Swagger's (current) goals.

One can say that you can randomize a value based on the type and use that for the curl command.

You can, in turn, argue that the same can be said about models. However, the examples are there mostly for documentation purposes to give the reader a clearer view of the model structure which can get fairly complex. You can't really say the same thing for primitives.

[Kegsay]

+1 for automatic generation of curl examples. At the moment I'm having to use x-example on the Parameter Object. I really don't think that the spec should be encouraging examples in the description field as per:

A brief description of the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.

I don't think this should contain examples because typically you want to put examples separate to the description of the field e.g:

Param   Location  Type     Description
--------------------------------------
 foo     path    string  This is a foo. E.g. "ab_cd".

Example:
GET /some/path/ab_cd

In this scenario, I want to mention the example ab_cd exactly once and use it for both the example at the bottom and possibly as an example at the end of the description. By encouraging the mixing of example and description, the spec makes this difficult to do.

[jharmn]

Link to parent #565

[leandroferreira]

+1

[oliver-xapix-io]

+1

[ePaul]

Please note that you don't need to add a new comment for a "+1" anymore – there is the reaction button (on the top left of each comment) which allow you to "vote" on a comment. (@etki)

Only add a comment if it actually adds something.

[JD557]

I believe that this is now fixed (see https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#examples-object)

[tadhgpearson]

@JD557 - I don't believe so.

I would have expected to see this example field in the schema object or the parameter object. The 'fixed fields' part of the schema object seems to suggest that this might be the case, but I only see examples of the usages of this schema provided for the requestBody, not for query parameters.

So it's unclear to me if this is covered by the specification, and if so, what it might look like in real life.

[darrelmiller]

@tadhgpearson The Schema Object now has both example and examples in the fixed fields definition https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#fixed-fields-17

So, I would say currently, if schema supports it and parameters support schema then transitively parameters support examples. Having said that, there is still work that needs doing on parameter, so this may change.

[tadhgpearson]

Yep... so it looks something like this?

        - name: origin
          in: query
          description: The [IATA code](https://en.wikipedia.org/wiki/International_Air_Transport_Association_airport_code) of the city from which the traveler will depart. See the location and airport interfaces for more information.
          required: true
          schema:
              type: string
              pattern: "^[A-Z]{3}$"
              example  NYC

[darrelmiller]

With the extra colon after example, yup. That's how I understand it to work.

[webron]

Parameter Object now has example AND examples, because we figured why not!