feat: add SerializeAsJsonAsync overloads accepting OpenApiJsonWriterS…#2985
Open
Mahdigln wants to merge 2 commits into
Open
feat: add SerializeAsJsonAsync overloads accepting OpenApiJsonWriterS…#2985Mahdigln wants to merge 2 commits into
Mahdigln wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
Adds new serialization overloads to allow callers to supply OpenApiJsonWriterSettings / OpenApiWriterSettings (notably enabling compact/minified JSON via Terse = true) when serializing OpenAPI elements to streams or strings, avoiding the need to post-process JSON output.
Changes:
- Add
SerializeAsJsonAsyncoverloads that acceptOpenApiJsonWriterSettingsfor both stream and string outputs. - Add a
SerializeAsyncstring-returning overload that acceptsOpenApiWriterSettings?. - Add unit tests validating compact vs pretty JSON output, and register new APIs in
PublicAPI.Unshipped.txt.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| test/Microsoft.OpenApi.Tests/Extensions/OpenApiSerializableExtensionsTests.cs | Adds tests for compact JSON via new settings-based overloads and formatted JSON via the new string-returning overload. |
| src/Microsoft.OpenApi/PublicAPI.Unshipped.txt | Registers the newly added public overload signatures. |
| src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs | Introduces the new overloads and adds RS0027 suppressions around existing shipped methods. |
Comment on lines
+24
to
+26
| #pragma warning disable RS0027 // The settings overload below has the same parameter count but different types; no ambiguity exists. | ||
| public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default) | ||
| #pragma warning restore RS0027 |
Comment on lines
+123
to
126
| #pragma warning disable RS0027 // The settings-bearing SerializeAsync overloads below have the same parameter count but different types; no ambiguity exists. | ||
| public static Task SerializeAsync<T>(this T element, IOpenApiWriter writer, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default) | ||
| #pragma warning restore RS0027 | ||
| where T : IOpenApiSerializable |
baywet
requested changes
Jul 22, 2026
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs:24
- This RS0027 suppression comment says the settings overload below has the same parameter count, but the current settings overload has an extra CancellationToken parameter, so the comment is inaccurate (even if the suppression itself is still needed). Please update the rationale comment to match the actual overload set.
#pragma warning disable RS0027 // The settings overload below has the same parameter count but different types; no ambiguity exists.
Comment on lines
+41
to
+45
| public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, OpenApiJsonWriterSettings settings, CancellationToken cancellationToken) | ||
| where T : IOpenApiSerializable | ||
| { | ||
| return element.SerializeAsync(stream, specVersion, OpenApiConstants.Json, settings, cancellationToken); | ||
| } |
baywet
requested changes
Jul 23, 2026
| /// <param name="specVersion">The Open API specification version.</param> | ||
| /// <param name="settings">Settings controlling JSON output, including <see cref="OpenApiJsonWriterSettings.Terse"/> for compact formatting.</param> | ||
| /// <param name="cancellationToken">The cancellation token.</param> | ||
| public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, OpenApiJsonWriterSettings settings, CancellationToken cancellationToken) |
Member
There was a problem hiding this comment.
the cancellation token should be optional
| public static Task<string> SerializeAsJsonAsync<T>( | ||
| this T element, | ||
| OpenApiSpecVersion specVersion, | ||
| OpenApiJsonWriterSettings settings) |
Member
There was a problem hiding this comment.
missing the cancellation token here
| this T element, | ||
| OpenApiSpecVersion specVersion, | ||
| string format, | ||
| OpenApiWriterSettings? settings) |
Member
There was a problem hiding this comment.
missing the cancellation token here
| var settings = new OpenApiJsonWriterSettings { Terse = true }; | ||
|
|
||
| using var stream = new MemoryStream(); | ||
| await parameter.SerializeAsJsonAsync(stream, OpenApiSpecVersion.OpenApi3_1, settings, CancellationToken.None); |
Member
There was a problem hiding this comment.
we should be passing the test context cancellation token instead
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add
SerializeAsJsonAsyncandSerializeAsyncoverloads that acceptOpenApiJsonWriterSettings, enabling callers to produce compact (minified) JSON output without having to parse and re-serialize the result.Type of Change
Related Issue(s)
Closes #2798
Changes Made
SerializeAsJsonAsync<T>(Stream, OpenApiSpecVersion, OpenApiJsonWriterSettings)overloadSerializeAsJsonAsync<T>(OpenApiSpecVersion, OpenApiJsonWriterSettings)overload returningstringSerializeAsync<T>(OpenApiSpecVersion, string, OpenApiWriterSettings?)overload returningstringPublicAPI.Unshipped.txtTesting
Tests cover:
Terse = truevia stream overload produces compact JSONTerse = truevia string overload produces compact JSONTerse = falsevia stringSerializeAsyncoverload produces pretty-printed JSONChecklist
Versions applicability
Additional Notes
The three new overloads intentionally omit the
CancellationTokenparameter to avoid RS0026/RS0027 analyzer violations that arise from adding optional-parameter overloads alongside existing shipped ones. Callers who need both custom settings and cancellation support can use the existingSerializeAsync(Stream, OpenApiSpecVersion, string, OpenApiWriterSettings?, CancellationToken)overload directly.#pragma warning disable RS0027is applied to four existing shipped methods where the analyzer fires a false positive: the new overloads use distinct types (OpenApiJsonWriterSettingsvsCancellationToken) so no call-site ambiguity exists.