Parameters Object does not list examples field

[DavidBiesack]

I looked at #636 again after @darrelmiller posted "Extending representations to parameters and headers" #762 . I think the Parameter Object section should include the (singular) example field under Fixed Fields. examples are used in parameters in the samples under Examples Object :

# in a parameter

  parameters:
    - name: 'zip'
      in: 'query'
      type: 'string'
      format: 'zip'
      example: 
        $ref: 'http://foo.bar#/examples/zip-example'

Also, given the ongoing discussions about multiple representations/content in #762 the example or examples field should be added to content (was representations) content object, as examples and content objects should apply to parameters as well.

[darrelmiller]

@DavidBiesack It's there https://github.com/OAI/OpenAPI-Specification/pull/761/files#diff-4a97aef5bba9ddb7fd8609f48f4bdc30R906 in the docs for the 'representation/content' object. I haven't updated the spec PR regarding parameters/headers yet because that is still being debated.

[DavidBiesack]

Thanks @darrelmiller -- is it worth splitting that off into a separate PR, since the examples #636 is already merged but the representations/content PR #761 is still a proposal?

[fehguy]

Both merged now