-
Notifications
You must be signed in to change notification settings - Fork 396
use of __example observations #722
Description
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.