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

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.

[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.

[msftbot[bot]]

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.