Allow for responses and parameters shared across all endpoints

[dsample]

Similar to Parameters and Servers being part of the Path Item Object schema, Parameters being part of the root schema, and Responses being part of the Path Item Object and root schemas would be useful.

Responses

This would be useful for services using CDN/throttling services (eg. CloudFlare) which have responses at a higher level than each endpoint (eg. 429). It would also be useful when a service has standard error response schemas for 400, 502, and 504 statuses.

It might also be useful for others to be able to define responses at Path Item level too. This is similar to Parameters and Servers

Parameters

This would be useful for common required headers (eg. OpenTracing). We have a couple of IDs we require on all requests, so it would be nice to not have to repeat ourselves throughout our API specs.

[darrelmiller]

One of the items on our possibility list #1466 for 3.1 is being able to re-use groups of parameters. That should help with common required headers. It's still not quite as clean as being able to do it once at the root. However, my concern with doing it at the root, is immediately we will get the request to do exceptions and that just gets complicated and ugly.

The global responses is an interesting one. I'll add a review label and we will bring it up at the @OAI/tsc meeting on Monday.

[dsample]

@darrelmiller, any update on this? I see from the minutes (#1581) that you ran out of time.

Responding to one of your points you made:

my concern with doing it at the root, is immediately we will get the request to do exceptions and that just gets complicated and ugly.

If the definition were explicitly around the requirement of common headers across all endpoints, I don't think it would be unreasonable to reject requests to allow exceptions. I can't think of anything else in the spec which would have exceptions, so it's not an established pattern (I don't think even JSON Schema allows exceptions).

[darrelmiller]

@dsample I will bring it up in the meeting today at 12EST.

[MikeRalphson]

Related: OAI/Overlay-Specification#34

[darrelmiller]

@dsample We didn't have much time left to discuss this, but there is a feeling that our work on grouping parameters and possibly the implementation of RAML like traits may help to address this need. We will continue the conversation next week.

[handrews]

I don't think even JSON Schema allows exceptions

What sort of exceptions?

[dsample]

@handrews, the exception requirement @darrelmiller mentions concerns about in his original reply. My point being that I think it's not a valid concern.

[darrelmiller]

See OAI/Overlay-Specification#34 #1466 instead.