-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
The Response object's default
field is confusing and inconsistently interpreted
#3396
Comments
@ahl looking over this to see where it might fit in terms of releases and SemVer, I have a few questions:
I agree that regardless, the wording of the examples is misleading, so I will tag this for 3.0.4 and 3.1.1 as those aspects should be fixed in those patch versions, regardless of what might happen in 3.2. |
I'm also going to tag this as "3.0 needs documentation" because we could explain it on the learn.openapis.org site and I think that's what that label is for (@MikeRalphson @webron is that correct? I guess I could file it over on the OAI/Documentation repo instead?) |
I want to describe an operation that
In other words, if the API were to erroneously respond with a 204 there would be no guarantee that the response body conformed to the same schema as would, say, a 400 response.
I think that's the accurate way of describing the example. Why don't others just do that? I'd imagine they're being less precise, are confused, or are blithely following examples... from the OAI org. What would you say an intended or well-formed use of
Again, consider this example: https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml Do the operations return a single success code or might there be other ones? If the operation above responded with a 204 would its response body conform to |
@handrews the |
In my opinion, the onus is on you to document the known responses. When you say "if the API were to erroneously respond with a 204 there would be no guarantee that the response body conformed to the same schema as would, say, a 400 response", that's not an OpenAPI problem. If your API can return a |
On the API description author... sure! I would merely observe that mistakes have occurred in the past, and are likely to occur in the future.
Perhaps the hypothetical was confusing. How about this: Consider https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml |
It does say that. It says, for the
So if you only document |
The additional detail I suggested was intentionally to distinguish it from the existing definition of "default". In particular the language "in categories not covered by explicit or ranged responses". This may be another case where more words would be clearer than fewer. My suggestion is that default would apply to status code ranges that are otherwise not mentioned. For example, if there is an entry for a 200, then default would not apply to the 2xx range. If there was a 404, default would similarly not apply to the 400 range. Put perhaps another way. A common use of default is to cover the 4xx and 5xx range with an error response type. I think there would be utility in a spec being able to say "this is what a 200 response looks like and there will be no other 2xx responses". Or perhaps "default" is insufficiently specific, and an "error" response that covers the 4xx and 5xx range would be more useful and intelligible. |
This would be a breaking change, so it couldn't be done until OAS 4 "Moonwalk" where things are being re-imagined on a larger scale, including API-level responses. You might want to follow those discussions to see if there's an analogous concern with the new format. On the one hand, I kind of like the |
According both 3.0 and 3.1, in the
Response
object there MUST be at least one response code and it SHOULD be the response for a successful operation call. In addition the default describes “responses other than the ones declared for specific HTTP response codes”.This means that if we had a
200
response anddefault
, the latter would cover everything except for200
. Many seem to interpretdefault
to mean something like response categories not covered by explicit response codes. Consider this example from the OAI org:https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml
This implies that
default
covers error types when in fact it covers non-error responses as well. In fact, the consumer wouldn't necessarily know if the API might reply with another success code such as a204
. A more precise example might look like this:I would suggest the following actions:
default
since this confusion is not limited to this example, but extends to APIs in the wilddefault
error
category that means "both 4xx and 5xx". This could be used in the way thatdefault
is often misused todayThe text was updated successfully, but these errors were encountered: