Update responses section with controllers metadata information #33739
Conversation
|
@Rick-Anderson @tdykstra @captainsafia I think this is ready for review / feedback. |
Co-authored-by: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com>
Co-authored-by: Tom Dykstra <tdykstra@microsoft.com>
| * the schema for the response body of 3xx and 5xx responses is considered to be not specified, | ||
| * the content-type for the response body can be inferred from the return type of the action method and the set of output formatters. | ||
|
|
||
| Note that there is no build-time validation of the OpenAPI metadata for responses in controller-based apps. For example, there is no build error issued if an action method returns a different status code than one specified by a <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute, and may return an object of a different type than specified in the <xref:Microsoft.AspNetCore.Mvc.ActionResult%601> return type of the action method. |
There was a problem hiding this comment.
@captainsafia Please give this paragraph extra scrutiny.
There was a problem hiding this comment.
Ditto the above comment about build-time vs run-time.
One caveat with MVC is that we do have analyzers that might actually catch some inconsistencies although I dunno if we want to wade into the weeds with that...
|
|
||
| OpenAPI supports providing a description of the responses returned from an API. Minimal APIs support three strategies for setting the response type of an endpoint: | ||
| Similar to controller-based apps, there is no build-time validation of the OpenAPI metadata specified with the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method or the <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute. For example, there is no build error issued: |
There was a problem hiding this comment.
@captainsafia Another part to give extra scrutiny.
There was a problem hiding this comment.
"build-time validation" feels like an unfamiliar turn of phrase for me, but I'm having trouble coming up with better alternatives. Perhaps this is fine given that you provide examples below.
Update: also I think what we mean here is "run-time validation"? As in these attributes don't directly change behavior of the API?
| * Via the [`ProducesResponseType`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute) attribute on the route handler. | ||
| * By returning<xref:Microsoft.AspNetCore.Http.TypedResults> from the route handler. | ||
| * If an endpoint returns a different status code than specified by a <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute. | ||
| * When the endpoint method returns an object of a different type than specified in the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method. |
There was a problem hiding this comment.
Should we add that the content-types don't influence content negotiation either?
Co-authored-by: Safia Abdalla <safia@microsoft.com>
Update responses section to describe how to add OpenAPI response metadata for controller-based apps.
Internal previews