Fix and Edit build time OpenAPI/ra

[Rick-Anderson]

Branch of #33359 Merges into #33359 Fixes #33391

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/openapi/aspnetcore-openapi.md	Work with OpenAPI documents
aspnetcore/fundamentals/openapi/buildtime-openapi.md	Generate OpenAPI documents at build time

[Rick-Anderson]

@martincostello please review

Public review of the doc build:

• download the HTML files
• unzip
• view HTML file in a browser.
• For links outside the doc, remove the review. from URL.

[martincostello]

Any chance you could change the OpenApiGenerateDocumentsOptions to NOT use -- for options?

I think changing that would break existing usage of the tool for NSwag and Swashbuckle.

Maybe use MSBuild conditions to "comment out" the property instead of literal comments?

<PropertyGroup Condition=" '$(DoTheThing)' == 'true' ">
  <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

[captainsafia]

Any chance you could change the OpenApiGenerateDocumentsOptions to NOT use -- for options?

We won't be able to do anything for .NET 9 with this particular issue.

We are planning on overhauling how build-time document generation works for .NET to avoid relying on command-line invocation but for now we'll have to deal with some of these issues.

[Rick-Anderson]

@captainsafia can you look this over and let me know what needs to change/delete before I can S&M it into your #33359? I'll then fix the merge conflicts in your #33359.