Extend the @opExample decorator to support example values for path / query string parameters

[dmytrol]

Clear and concise description of the problem

Currently it looks like @opExample can only be used to provide example values for payloads in the request body. It would be extremely useful to add an ability to provide examples for path / query string parameters as well.

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[timotheeguerin]

I totally agree, that just turned about to be quite painful to implement without some better help from the http library to understand the mapping. As a workaround for now you should be able to use @example on the parameter itself.

But basically we need the following for this:

1. Http library needs to expose a mapping of where each entity in parameters and returnType goes(in body, in header, in path, etc.)
2. And probably the inverse as well(Path from the root so we can compare with the example) not just the property that we have today
3. When traversing the value we pick what we want from this mapping

[dmytrol]

As a workaround for now you should be able to use @example on the parameter itself.

@timotheeguerin Many thanks for the hint! I did try that, but, alas, it didn't work. Maybe because the types of my parameters are scalars that do have their own @example decorator applied at the scalar level.

However, in the end none of the examples (neither the one at the scalar definition level nor the one at the parameter level) get promoted to the operation definition YAML (but should they? 😕 ). The generated YAML is something like:

# -------- some operation ---------
  parameters:
        - name: host
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/host'

# -------- schemas ----------

host:
  type: string
  example: api.www
  minLength: 1
  maxLength: 255
  format: hostname

[timotheeguerin]

ah yeah no i wouldn't expect to be promoted up, just saying this so it gets included in the spec

[Arithmomaniac]

Parameter examples are used heavily by Sefaria, and their lack of support will be a major impediment to adoption (cc @markcowl).

Maybe there should be a separate @paramExample decorator? After all, reading the OpenAPI spec, parameter examples are clearly decoupled from request/response examples. (They also appear to be the only example type not supported by the emitter today.)