Skip to content

use of __example observations #722

@equalspeterd

Description

@equalspeterd

Not sure if this is a bug or a feature request, so I will start here with a question/observation, and convert as appropriate.

selecting response examples
when using ?__example=foo request parameters to select response examples, prism assumes that only a response object body is requested (as evidenced by the response error), and not examples defined elsewhere in the specification (e.g. headers):

POST /bar?__example=myHeaderExample

{
    "type": "https://stoplight.io/prism/errors#NOT_FOUND",
    "title": "The server cannot find the requested content",
    "status": 404,
    "detail": "Response for contentType: application/json and exampleKey: myHeaderExample does not exist."
}

despite having defined:

Location:
      description: the URI of a newly created resource
      required: true
      schema:
        type: string
        format: uri
        pattern: https://example.com/.*
      examples:
        myHeaderExample:
          value: 'https://example.com/foo'

(no application/json example named myHeaderExample was defined in the response content).

I totally understand the challenge here, as openAPI does no properly define a response object with an examples property. Rather, it relies on explicit parameter examples and media-type examples (and I don't see that changing anytime soon). However, a documented profile in prism could resolve this deficiency, when both a parameter named example and a media-type named example shared the same name, each could be used in constructing a response. Food for thought.

The observation I had was why you choose to respond with a 404 if a named example is not found. That seems odd (to me at least). The resource was found, just not a suitable representation (the sought-after example). My €0.02.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions