fix: use settings for terse output in serialization extension methods

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -192,16 +192,17 @@ private static async Task WriteOpenApiAsync(HidiOptions options, string openApiF
                 using var outputStream = options.Output.Create();
                 using var textWriter = new StreamWriter(outputStream);
 
-                var settings = new OpenApiWriterSettings
+                var settings = new OpenApiJsonWriterSettings
                 {
                     InlineLocalReferences = options.InlineLocal,
-                    InlineExternalReferences = options.InlineExternal
+                    InlineExternalReferences = options.InlineExternal,
+                    Terse = options.TerseOutput
                 };
 #pragma warning disable CA1308
                 IOpenApiWriter writer = openApiFormat.ToLowerInvariant() switch
 #pragma warning restore CA1308
                 {
-                    OpenApiConstants.Json => options.TerseOutput ? new(textWriter, settings, options.TerseOutput) : new OpenApiJsonWriter(textWriter, settings, false),
+                    OpenApiConstants.Json => new OpenApiJsonWriter(textWriter, settings),
                     OpenApiConstants.Yaml => new OpenApiYamlWriter(textWriter, settings),
                     _ => throw new ArgumentException("Unknown format"),
                 };

src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs

@@ -21,7 +21,7 @@
         /// <param name="stream">The output stream.</param>
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
             return element.SerializeAsync(stream, specVersion, OpenApiConstants.Json, cancellationToken);
@@ -35,7 +35,7 @@
         /// <param name="stream">The output stream.</param>
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         public static Task SerializeAsYamlAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
             return element.SerializeAsync(stream, specVersion, OpenApiConstants.Yaml, cancellationToken);
@@ -51,7 +51,7 @@
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="format">The output format (JSON or YAML).</param>
         /// <param name="cancellationToken">The cancellation token.</param>
         public static Task SerializeAsync<T>(
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
@@ -88,7 +88,8 @@
 
             IOpenApiWriter writer = format.ToLowerInvariant() switch
             {
-                OpenApiConstants.Json => new OpenApiJsonWriter(streamWriter, settings, false),
+                OpenApiConstants.Json when settings is OpenApiJsonWriterSettings jsonSettings => new OpenApiJsonWriter(streamWriter, jsonSettings),
+                OpenApiConstants.Json => new OpenApiJsonWriter(streamWriter, settings),
                 OpenApiConstants.Yaml => new OpenApiYamlWriter(streamWriter, settings),
                 _ => throw new OpenApiException(string.Format(SRResource.OpenApiFormatNotSupported, format)),
             };

src/Microsoft.OpenApi/Writers/OpenApiJsonWriter.cs

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System;
+using System.ComponentModel;
 using System.IO;
 
 namespace Microsoft.OpenApi
@@ -14,7 +16,17 @@
         /// Initializes a new instance of the <see cref="OpenApiJsonWriter"/> class.
         /// </summary>
         /// <param name="textWriter">The text writer.</param>
-        public OpenApiJsonWriter(TextWriter textWriter) : base(textWriter, null)
+        public OpenApiJsonWriter(TextWriter textWriter) : this(textWriter, (OpenApiWriterSettings?)null)
+        {
+			// this constructor is kept for binary compatibility
+            // TODO remove in next major version and make the settings an optional parameter in the other constructor
+		}
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OpenApiJsonWriter"/> class.
+        /// </summary>
+        /// <param name="settings">Settings for controlling how the OpenAPI document will be written out.</param>
+        /// <param name="textWriter">The text writer.</param>
+        public OpenApiJsonWriter(TextWriter textWriter, OpenApiWriterSettings? settings) : base(textWriter, settings ?? new OpenApiJsonWriterSettings())
         {
         }
 
@@ -34,9 +46,13 @@
         /// <param name="textWriter">The text writer.</param>
         /// <param name="settings">Settings for controlling how the OpenAPI document will be written out.</param>
         /// <param name="terseOutput"> Setting for allowing the JSON emitted to be in terse format.</param>
-        public OpenApiJsonWriter(TextWriter textWriter, OpenApiWriterSettings? settings, bool terseOutput = false) : base(textWriter, settings)
+        [Obsolete("Use OpenApiJsonWriter(TextWriter textWriter, OpenApiJsonWriterSettings settings) instead.")]
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public OpenApiJsonWriter(TextWriter textWriter, OpenApiWriterSettings? settings, bool terseOutput) : base(textWriter, settings)
         {
             _produceTerseOutput = terseOutput;
+            // this constructor is kept for binary compatibility, terse information should be read from the settings to avoid fork APIs.
+            // TODO remove in next major version
         }
 
         /// <summary>

src/Microsoft.OpenApi/Writers/OpenApiWriterBase.cs

@@ -55,10 +55,7 @@
             Writer.NewLine = "\n";
 
             Scopes = new();
-            if (settings == null)
-            {
-                settings = new();
-            }
+            settings ??= new();
             Settings = settings;
         }
 
@@ -133,7 +130,7 @@
         /// Write float value.
         /// </summary>
         /// <param name="value">The float value.</param>
         public virtual void WriteValue(float value)
         {
             WriteValueSeparator();
             Writer.Write(value);

test/Microsoft.OpenApi.Tests/Extensions/OpenApiSerializableExtensionsTests.cs

@@ -0,0 +1,93 @@
+using System.IO;
+using System.Threading.Tasks;
+using Xunit;
+
+namespace Microsoft.OpenApi.Tests.Extensions;
+
+public class OpenApiSerializableExtensionsTests
+{
+    [Fact]
+    public async Task UsesTheTerseOutputInformationFromSettingsTrue()
+    {
+        var parameter = new OpenApiParameter
+        {
+            Name = "param1",
+            In = ParameterLocation.Query,
+            Description = "A sample parameter",
+            Required = false,
+            Schema = new OpenApiSchema
+            {
+                Type = JsonSchemaType.String
+            }
+        };
+
+        var settings = new OpenApiJsonWriterSettings
+        {
+            Terse = true
+        };
+
+        using var stream = new MemoryStream();
+        await parameter.SerializeAsync(stream, OpenApiSpecVersion.OpenApi3_1, OpenApiConstants.Json, settings);
+
+        stream.Position = 0;
+        using var reader = new StreamReader(stream);
+        var output = await reader.ReadToEndAsync();
+
+        Assert.Equal("{\"name\":\"param1\",\"in\":\"query\",\"description\":\"A sample parameter\",\"schema\":{\"type\":\"string\"}}", output);
+    }
+
+    [Fact]
+    public async Task UsesTheTerseOutputInformationFromSettingsFalse()
+    {
+        var parameter = new OpenApiParameter
+        {
+            Name = "param1",
+            In = ParameterLocation.Query,
+            Description = "A sample parameter",
+            Required = false,
+            Schema = new OpenApiSchema
+            {
+                Type = JsonSchemaType.String
+            }
+        };
+
+        var settings = new OpenApiJsonWriterSettings
+        {
+            Terse = false
+        };
+
+        using var stream = new MemoryStream();
+        await parameter.SerializeAsync(stream, OpenApiSpecVersion.OpenApi3_1, OpenApiConstants.Json, settings);
+
+        stream.Position = 0;
+        using var reader = new StreamReader(stream);
+        var output = await reader.ReadToEndAsync();
+
+        Assert.Equal("{\n  \"name\": \"param1\",\n  \"in\": \"query\",\n  \"description\": \"A sample parameter\",\n  \"schema\": {\n    \"type\": \"string\"\n  }\n}", output);
+    }
+
+    [Fact]
+    public async Task UsesTheTerseOutputInformationFromSettingsNoSettings()
+    {
+        var parameter = new OpenApiParameter
+        {
+            Name = "param1",
+            In = ParameterLocation.Query,
+            Description = "A sample parameter",
+            Required = false,
+            Schema = new OpenApiSchema
+            {
+                Type = JsonSchemaType.String
+            }
+        };
+
+        using var stream = new MemoryStream();
+        await parameter.SerializeAsync(stream, OpenApiSpecVersion.OpenApi3_1, OpenApiConstants.Json, null);
+
+        stream.Position = 0;
+        using var reader = new StreamReader(stream);
+        var output = await reader.ReadToEndAsync();
+
+        Assert.Equal("{\n  \"name\": \"param1\",\n  \"in\": \"query\",\n  \"description\": \"A sample parameter\",\n  \"schema\": {\n    \"type\": \"string\"\n  }\n}", output);
+    }
+}

test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

@@ -795,7 +795,10 @@ namespace Microsoft.OpenApi
     {
         public OpenApiJsonWriter(System.IO.TextWriter textWriter) { }
         public OpenApiJsonWriter(System.IO.TextWriter textWriter, Microsoft.OpenApi.OpenApiJsonWriterSettings settings) { }
-        public OpenApiJsonWriter(System.IO.TextWriter textWriter, Microsoft.OpenApi.OpenApiWriterSettings? settings, bool terseOutput = false) { }
+        public OpenApiJsonWriter(System.IO.TextWriter textWriter, Microsoft.OpenApi.OpenApiWriterSettings? settings) { }
+        [System.Obsolete("Use OpenApiJsonWriter(TextWriter textWriter, OpenApiJsonWriterSettings settings) " +
+            "instead.")]
+        public OpenApiJsonWriter(System.IO.TextWriter textWriter, Microsoft.OpenApi.OpenApiWriterSettings? settings, bool terseOutput) { }
         protected override int BaseIndentation { get; }
         public override void WriteEndArray() { }
         public override void WriteEndObject() { }