Restructure of OpenAPI docs for .NET 9

[mikekistler]

This PR attempts to restructure the OpenAPI docs for .NET 9, while leaving the docs for .NET 8 and previous as is.

The intent is to split the current "Generating OpenAPI document" article, which currently covers both how to generate the document and how to customize it, into two separate articles, focusing on each aspect individually.

While this looks like a large change, it is mostly just moving some content from the existing article to a new one, and updating the links in the table of contents and within the articles themselves.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/openapi/aspnetcore-openapi.md	aspnetcore/fundamentals/openapi/aspnetcore-openapi
aspnetcore/fundamentals/openapi/customize-openapi.md	aspnetcore/fundamentals/openapi/customize-openapi
aspnetcore/fundamentals/openapi/include-metadata.md	aspnetcore/fundamentals/openapi/include-metadata
aspnetcore/toc.yml	aspnetcore/toc

[mikekistler]

I just reworked this to pull in Sofia's changes to describe build time generation of OpenAPI documents.

[captainsafia]

@mikekistler What are your thoughts on adding a section to the "Generate OpenAPI documents" page under "Configure OpenAPI document generation that covers what kind of customizations can be made on the document? I'm thinking about things like being able to change the document name by passing an argument the AddOpenApi call or changing the default route of the OpenAPI document in the MapOpenApi call.

Also, I feel like transformers should go at the top of the "Customize OpenAPI documents" page instead of at the bottom. Thoughts?

[mikekistler]

Regarding:

What are your thoughts on adding a section to the "Generate OpenAPI documents" page under "Configure OpenAPI document generation" that covers what kind of customizations can be made on the document?

I think that content is there but may be difficult to find because of the way I inserted the build-time generation content.

Here's the "table of contents" for the "Generate OpenAPI documents" article:

>grep '^#\+ [^[]' $f 
# Generate OpenAPI documents
## Package installation
## Configure OpenAPI document generation
## Generate OpenAPI documents at build-time
### Customizing build-time document generation
#### Modifying the output directory of the generated Open API file
#### Modifying the output file name
#### Selecting the OpenAPI document to generate
### Customizing run-time behavior during build-time document generation
## Options to Customize OpenAPI document generation
### Customize the OpenAPI document name
### Customize the OpenAPI version of a generated document
### Customize the OpenAPI endpoint route
### Customize the OpenAPI endpoint
#### Limit OpenAPI document access to authorized users
#### Cache generated OpenAPI document

I think the content you are suggesting is in the "Options to Customize OpenAPI document generation". I inserted the section for generation at build time above that, but maybe it would be better to move that to the end? I am fine either way, so just let me know your preference.

[mikekistler]

Regarding:

I feel like transformers should go at the top of the "Customize OpenAPI documents" page instead of at the bottom.

I think the 80% use case will be that developers use the built-in mechanisms for adding metadata, and that transformers will be an advance use case that developers reach for only when a built-in mechanism isn't available. Based on this, I think the built-in mechanisms should be before the advanced use cases.

But another option is to separate these into two different articles, which might be better for folks to quickly find the content they want. Now that I've mentioned this I kinda like this idea. What do you think?

[captainsafia]

I inserted the section for generation at build time above that, but maybe it would be better to move that to the end?

Yep, that's exactly it. I was proposing moving "## Options to Customize OpenAPI document generation" between "## Configure OpenAPI document generation" and "## Generate OpenAPI documents at build-time".

But another option is to separate these into two different articles, which might be better for folks to quickly find the content they want. Now that I've mentioned this I kinda like this idea. What do you think?

This is my preference too. It also gives us a nicer place to land snippets of various transformers that people can use for common scenarios (e.g. changing enum handling).

[mikekistler]

@captainsafia I have pushed some updates that I hope address your comments. Please have another look.

[mikekistler]

@tdykstra This PR has one build warning:

[Warning] File aspnetcore/fundamentals/openapi/buildtime-openapi.md with URL /aspnet/core/fundamentals/openapi/buildtime-openapi was deleted without redirection. To avoid broken links, add a redirection.

The URL identified was only added a few days ago by Sofia's PR so I don't think a redirection is really needed. Can we suppress this somehow or do we just add the redirect to satisfy the tooling?

[tdykstra]

The URL identified was only added a few days ago by Sofia's PR so I don't think a redirection is really needed. Can we suppress this somehow or do we just add the redirect to satisfy the tooling?

Ignore the warning and merge the PR, it's a PR-level warning so it will go away after this PR is merged.

[captainsafia]

Sorry I missed your ping here! Looks great!

[mikekistler]

@tdykstra The merge was blocked until the warning was resolved so I just added the redirect to be able to move forward.
Do you want to give this a quick review or am I okay to merge this?

[tdykstra]

Okay to merge.
A few nit suggestions for you to look at first.