Improve build-time OpenAPI document generation

[captainsafia]

This is a meta-issue to track a set of improvements that can be made to the tooling we currently provide for generating OpenAPI documents at build-time.

Build-time OpenAPI document generation issue currently supported by the Microsoft.Extensions.ApiDescription.Server package and was primarily implemented with the assumption that another package (like Swashbuckle or NSwag) would be installed alongside it.

Here's a braindump of the current issues with the design and how we might improve them in the future:

• The current implementation uses an internal executable that is called via MSBuild, so there's massaging that needs to be done when mapping the MSBuild arguments to arguments for the CLI tool. IMO, we should ship either a tool or stick to MSBuild targets. I don't think there's much value in providing half-baked support for both.
• The current implementation is intended to work with tools like Swashbuckle, which support a wider set of target frameworks that we intend to. Moving to a different approach would allow us to remove code/packaging logic related to unsupported frameworks (netfx, netstandard).
• I'd like to standardize the configuration story for build-time document generation so there's an official schema exposed via options (similar to what you get with Aspire's config model) to improve the discoverability of these options.
• The current implementation relies on private reflection-based contract exposed via the “IDocumentProvider” interface. This interface should be fleshed out and made public.
• The current implementation will attempt to boot up the application's entry-point at build-time in oder to resolve the IDocumentProvider instance from the DI container. This can present issues for applications that resolve configuration at startup that might not exist when it is launched by the command line tool. Furthermore, it's difficult to detect when an application is being launched by the tool which makes it difficult to create conditional logic for this behavior.

This collection of issues and our overall investment in OpenAPI warrants another look here to see if we can establish something better and address something of these pain-points. The goals of this effort include:

• Reducing the reliance on internal or undocumented APIs for the implementation
• Streamline the process for configuring options for the command line tool
• Make it easier to stub out unavailable startup dependences in the entry points

[marinasundstrom]

I'm currently using NSwag. This API is currently limited compared to that.

Especially in how null is handled. And then inheritance.

But about null:

NSwag uses oneOf like this to represent nullable for referenced object schemas:

Bag:
        properties:
          count:
            type: integer
            format: int32
          item:
            nullable: true
            oneOf:
            - $ref: '#/components/schemas/Item'

Otherwise, if it's the requestBody, NSwag marks it as required.

For comparison:

https://github.com/marinasundstrom/NullabilityTransformersPrototype/blob/main/Client/OpenAPIs/v1-nswag.yaml

Controller:
https://github.com/marinasundstrom/NullabilityTransformersPrototype/blob/main/WebApi/Controllers/TestController.cs

[captainsafia]

@marinasundstrom I think you might've intended to post this comment on the issue tracking adoption of 3.1 support: #58619