Refactor "OpenAPI support in minimal API apps" and "Get started with Microsoft.AspNetCore.OpenApi"

[Rick-Anderson]

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

---

Associated WorkItem - 273722

[tdykstra]

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