Repository navigation
Add OpenApiDocument.SerializeAs(OpenApiSpecVersion, IOpenApiWriter) method #2231
Description
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
Activity
baywet commentedon Mar 12, 2025
Hi Martin Costello (@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 commentedon Mar 12, 2025
For Swashbuckle, I've only had need for this at the document level.
baywet commentedon Mar 12, 2025
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 commentedon Mar 12, 2025
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.
baywet commentedon Mar 12, 2025
Thanks, that's a great practice.
To be clear, this PR is only expected to contain changes in OpenApiDocument.
Go ahead, and let us know if you need anything else!
Add OpenApiDocument.SerializeAs()
martincostello commentedon Mar 13, 2025
#2253
Merge branch 'main' into microsoftgh-2231
Merge pull request #2253 from martincostello/gh-2231