Matching responses

[rafalkrupinski]

The example response in the project's Readme has a new property called apiResponses, which, I presume, contains api-global responses - that apply to all the operations.

Suppose the scenario where pathResponses has a responses with status: 4XX and apiResponses has status: 404 (alternatively 40X), both have the same content-type and the actual response has status 404.

Does the response in pathResponses takes precedence as being defined in more specific context (operation vs api-global) or is it apiResponse since it's more specific status code.

My answer would be to look at apiResponses only when pathResponses doesn't have any matching responses, but I guess the consistency with the rest of the specification should also be considered.

Similar question applies to status vs content-type:

404 Not found
content-type: application/json; param=value

matched against:

pathResponses:
  a:
    status: 40X
    contentType: application/json; param=value
  b:
    status: 404
    contentType: application/json

OAS 3.X had only one response map for each operation and put content-type under status code, which made the precedence clear.

[darrelmiller]

This is a great question and I think in my head I was imagining "most precise match wins". I would be interesting to see where that rule gets difficult to implement.