Add OpenApiDocument.SerializeAs(OpenApiSpecVersion, IOpenApiWriter) method

[martincostello]

Is your feature request related to a problem? Please describe.

In the process of upgrading domaindrivendev/Swashbuckle.AspNetCore to Microsoft.OpenApi v2, I've found the need to do something like this in a few places:

OpenApiDocument document = DocumentFromSomewhere();
IOpenApiWriter writer = WriterFromSomewhere();
OpenApiSpecVersion version = VersionFromSomewhere();

switch (version)
{
    case OpenApiSpecVersion.OpenApi2_0:
        document.SerializeAsV2(writer);
        break;

#if NET10_0_OR_GREATER
    case OpenApiSpecVersion.OpenApi3_1:
        document.SerializeAsV31(writer);
        break;
#endif

    case OpenApiSpecVersion.OpenApi3_0:
    default:
        document.SerializeAsV3(writer);
        break;
}

To make the code terser, reduce repetition, and make easier to evolve over time (e.g. OpenAPI 3.2 or 4.0), it would be beneficial if there were a method on OpenApiDocument that accepted a writer and a OpenApiSpecVersion version so the version switching logic is handled on behalf of the caller.

As those methods come from implementing IOpenApiSerializable (and it's already had a breaking change to add SerializeAsV31()) it should also be added to that interface.

Describe the solution you'd like

public partial class OpenApiDocument
{
+   public void SerializeAsVersion(OpenApiSpecVersion version, IOpenApiWriter writer)
+   {
+       // Similar switch logic to the above, except throwing if the value is unknown
+   }
}

public partial interface IOpenApiSerializable
{
+   void SerializeAsVersion(OpenApiSpecVersion version, IOpenApiWriter writer);
}

Describe alternatives you've considered

None.

Additional context

PR that suggested the need to me: domaindrivendev/Swashbuckle.AspNetCore#3283

[baywet]

Hi @martincostello
Thank you for using the SDK and for reaching out.

To be clear, would you need such a method only on the document or on all objects of the model?

[martincostello]

For Swashbuckle, I've only had need for this at the document level.

[baywet]

Thank you for the additional information.

I think that adding this facilitating method at the document level is probably acceptable as it doesn't grow the API surface too much.

Is this something you'd like to submit a pull request for provided some guidance?

[martincostello]

I can do - I figured I'd start with an issue rather than propose adding a new method (potentially on the interface too) that would then just be rejected for whatever possible design justification.