[.NET 9]: Refactor and revise OpenAPI docs

[captainsafia]

We're making some significant changes to the OpenAPI area in .NET 9. Namely:

• Adding built-in support for OpenAPI document generation
• Updating the web API templates to take advantage of the built-in support

As part of this, we'll want to refactor the docs on OpenAPI to reflect the state of the new universe.

AFAICT, we reference OpenAPI in a few pages in the docs:

• OpenAPI support in minimal APIs
• Swagger/OpenAPI under controller-based APIs
  • Includes "Getting started with NSwag" and "Getting started with Swashbuckle" sub-pages
• .NET OpenAPI tool reference
• Using OpenAPI with gRPC JSON transcoding
• Getting started with Swashbuckle and ASP.NET Core sample
• Generate a REST API client in a build

As part of this work, I'm recommending a revised header structure for our OpenAPI-related docs.

• Controller-based APIs
  • OpenAPI
    • Overview
    • Getting started with Microsoft.AspNetCore.OpenApi
    • Getting started with Swashbuckle
    • Getting started with NSwag
    • Working with OpenAPI at build-time
• Minimal APIs
  • OpenAPI
    • Overview
    • Getting started with Microsoft.AspNetCore.OpenApi
    • Getting started with Swashbuckle
    • Getting started with NSwag
    • Working with OpenAPI at build-time

The content under each of these pages should be the same, which conditional headers that allows us to show controller and minimal API specific code when necessary.

We'll also need to go in and revise any code blocks that reference UseSwagger/UseSwaggerUi to reference the new built-in APIs.

We'll probably want to have the first pass of this done to align with the preview4 release coming up in May. I'll create some draft content on the new APIs that we can incorporate here.

cc: @Rick-Anderson @tdykstra @JeremyLikness @mikekistler

[captainsafia]

@martincostello What are your thoughts on the current Swashbuckle doc page (ref)? I think most of the content on there is accurate but some of the additional resources might be updated.

@RicoSuter How about the NSwag page (ref)? I think the code generation section could use some sprucing. We don't mention the NSwag client generation via VS Connected services at all. And perhaps the screenshots need updating?

[martincostello]

@captainsafia Once we ship our 6.6.0 release with net8.0 support (in the next week or so 🤞) I was planning on reviewing the existing content to see what might need tweaking. At a minimum I was going to propose the "doesn't work with .NET 8" notes be removed.

[captainsafia]

At a minimum I was going to propose the "doesn't work with .NET 8" notes be removed.

That sounds like a good idea to me! What are your thoughts on the amount of content that is on there?

I'm not sure what the right balance between docs on this page and those we would link to externally in the Swashbuckle repo/elsewhere.

[martincostello]

I think the level of content there is fine - it seems to cover all the entry-level scenarios with a few troubleshooting hints. It might duplicate stuff that is (or should) be in our README, but I don't think there's anything in there that's out-of-date or incorrect from a quick scroll through.

I did notice there's a link off to domaindrivendev/Swashbuckle.AspNetCore#1920 at the end of the document, which is resolved for 6.6.0, so that can be removed once we ship that too.

[captainsafia]

@martincostello Great! TYSM for your help here.