Minimal APIs doesn't describe it's implicit 400 and 415 response behaviors to ApiExplorer

[DamianEdwards]

Minimal APIs today has a number of implicit behaviors that are performed implicitly based on the declared route handler delegate signature. Most of these behaviors are automatically described to ApiExplorer such that OpenAPI/Swagger libraries like Swashbuckle or nSwag can emit OpenAPI information that accurately reflects the behavior of the app's HTTP API endpoints.

Some implicit behaviors are not described however, namely:

• The implicit 400 Bad Request response in the case that the parameters for the matched route handler delegate cannot be populated from the request, e.g. due to a missing request body or route data parameter
• The implicit 415 Unsupported Media Type response in the case that the request's Content-Type header does not contain a value that matches either the implicit content type supported by Minimal APIs (application/json) or one of the specific content types declared by the ConsumesAttribute metadata on the route handler delegate

We should decide whether these (and any others I've missed) implicit behaviors should be described to ApiExplorer and if not what the principle is that guides which behaviors should and shouldn't be described moving forward.

[DamianEdwards]

Note this from the OpenAPI/Swagger spec suggests that known errors like 400 Bad Request due to invalid operations should be documented:

https://swagger.io/docs/specification/describing-responses/#status-codes

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By “known errors” we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.

[darrelmiller]

Personally, I would describe responses with:

responses:
  4XX:
    content-type:
      application/http-problem: {}
  5XX:
    content-type:
      application/http-problem: {}

Unfortunately this only works for Open v3.x

I don't believe there is a need to call out specific status codes unless there is something about the response that is out of the ordinary. A client should be designed to handle any HTTP status via fallback to 200/400/500, so I see no need to call out default 400,401,404, etc behaviors.

The wording in the spec sucks. What does "known" mean? It is very imprecise. Also, that link isn't the spec, despite what Smartbear say. The actual spec is here https://spec.openapis.org/oas/v3.1.0#responses-object and sadly has the same crappy language.

[ghost]

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s). If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s). If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.