dotnet
Refactor "OpenAPI support in minimal API apps" and "Get started with Microsoft.AspNetCore.OpenApi"
Description
@tdykstra please review Also applies to content health.
Some duplication but related content is scattered between the two docs
Refactor OpenAPI support in minimal API apps
OpenAPI support in minimal API apps
Describe endpoints
OpenAPI supports providing summaries and descriptions of routes that are registered in an app. Minimal APIs support two strategies for setting these properties on a given endpoint, using the following extension methods and attributes:
Summaries: WithSummary Descriptions: WithDescription Summaries: EndpointSummaryAttribute Descriptions: EndpointDescriptionAttribute
Get started with Microsoft.AspNetCore.OpenApi
Customize OpenAPI endpoints with endpoint metadata
The following list shows the endpoint metadata that is used to customize the generated OpenAPI document:
Summaries from IEndpointSummaryMetadata Descriptions from IEndpointDescriptionMetadata Request body from IAcceptsMetadata Response information from IProducesResponseTypeMetadata Operation IDs from IEndpointNameMetadata OpenAPI tags from ITagsMetadata To learn more about customizing the generated OpenAPI document by modifying endpoint metadata, see How to use OpenAPI in Minimal API apps.
Page URL
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/openapi?view=aspnetcore-9.0
Content source URL
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/minimal-apis/openapi.md
Document ID
b18acd86-50e3-2316-27be-27156651e5a8
Article author
@Rick-Anderson
@tdykstra please review
I just realized there's already a plan for this in another issue #32477 I would go with that plan as much as possible, and I'll just leave some general comments here:
- Overview - These would be basic introductions to OpenApi and its support in minimal API apps / controller-based API apps. Explain what OpenApi documents are and how they are used, what transformers are and how they are used. Minimal details about specific APIs / how to describe endpoint requests and response, etc.
- Get started docs - These would be tutorials - No attempt to do everything as in the how-to, but detailed guidance through creating a document, customizing endpoint descriptions, and using transformers. Include a section on using an OpenApi document, maybe with swagger UI, not just create a document.
- Working with OpenApi at build-time These would be how-tos, can have all the details about working with OpenApi.
