fix: inconsistant API surface usage

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -113,7 +113,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
                     var walker = new OpenApiWalker(powerShellFormatter);
                     walker.Walk(document);
                 }
-                WriteOpenApi(options, openApiFormat, openApiVersion, document, logger);
+                await WriteOpenApiAsync(options, openApiFormat, openApiVersion, document, logger, cancellationToken).ConfigureAwait(false);
             }
             catch (TaskCanceledException)
             {
@@ -191,7 +191,7 @@ private static OpenApiDocument ApplyFilters(HidiOptions options, ILogger logger,
             return document;
         }
 
-        private static void WriteOpenApi(HidiOptions options, OpenApiFormat openApiFormat, OpenApiSpecVersion openApiVersion, OpenApiDocument document, ILogger logger)
+        private static async Task WriteOpenApiAsync(HidiOptions options, OpenApiFormat openApiFormat, OpenApiSpecVersion openApiVersion, OpenApiDocument document, ILogger logger, CancellationToken cancellationToken)
         {
             using (logger.BeginScope("Output"))
             {
@@ -216,11 +216,11 @@ private static void WriteOpenApi(HidiOptions options, OpenApiFormat openApiForma
 
                 var stopwatch = new Stopwatch();
                 stopwatch.Start();
-                document.Serialize(writer, openApiVersion);
+                await document.SerializeAsync(writer, openApiVersion, cancellationToken).ConfigureAwait(false);
                 stopwatch.Stop();
 
                 logger.LogTrace("Finished serializing in {ElapsedMilliseconds}ms", stopwatch.ElapsedMilliseconds);
-                textWriter.Flush();
+                await textWriter.FlushAsync(cancellationToken).ConfigureAwait(false);
             }
         }
 
@@ -769,7 +769,7 @@ internal static async Task PluginManifestAsync(HidiOptions options, ILogger logg
             // Write OpenAPI to Output folder
             options.Output = new(Path.Combine(options.OutputFolder, "openapi.json"));
             options.TerseOutput = true;
-            WriteOpenApi(options, OpenApiFormat.Json, OpenApiSpecVersion.OpenApi3_1, document, logger);
+            await WriteOpenApiAsync(options, OpenApiFormat.Json, OpenApiSpecVersion.OpenApi3_1, document, logger, cancellationToken).ConfigureAwait(false);
 
             // Create OpenAIPluginManifest from ApiDependency and OpenAPI document
             var manifest = new OpenAIPluginManifest(document.Info?.Title ?? "Title", document.Info?.Title ?? "Title", "https://go.microsoft.com/fwlink/?LinkID=288890", document.Info?.Contact?.Email ?? "placeholder@contoso.com", document.Info?.License?.Url.ToString() ?? "https://placeholderlicenseurl.com")

src/Microsoft.OpenApi.Workbench/MainModel.cs

@@ -270,7 +270,7 @@ internal async Task ParseDocumentAsync()
 
                 stopwatch.Reset();
                 stopwatch.Start();
-                Output = WriteContents(document);
+                Output = await WriteContentsAsync(document);
                 stopwatch.Stop();
 
                 RenderTime = $"{stopwatch.ElapsedMilliseconds} ms";
@@ -299,23 +299,23 @@ internal async Task ParseDocumentAsync()
         /// <summary>
         /// Write content from the given document based on the format and version set in this class.
         /// </summary>
-        private string WriteContents(OpenApiDocument document)
+        private async Task<string> WriteContentsAsync(OpenApiDocument document)
         {
             var outputStream = new MemoryStream();
 
-            document.Serialize(
+            await document.SerializeAsync(
                 outputStream,
                 Version,
                 Format,
-                new()
+                (Writers.OpenApiWriterSettings)new()
                 {
                     InlineLocalReferences = InlineLocal,
                     InlineExternalReferences = InlineExternal
                 });
 
             outputStream.Position = 0;
 
-            return new StreamReader(outputStream).ReadToEnd();
+            return await new StreamReader(outputStream).ReadToEndAsync();
         }
 
         private static MemoryStream CreateStream(string text)

src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs

@@ -3,6 +3,8 @@
 
 using System.Globalization;
 using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Properties;
@@ -22,10 +24,11 @@ public static class OpenApiSerializableExtensions
         /// <param name="element">The Open API element.</param>
         /// <param name="stream">The output stream.</param>
         /// <param name="specVersion">The Open API specification version.</param>
-        public static void SerializeAsJson<T>(this T element, Stream stream, OpenApiSpecVersion specVersion)
+        /// <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
         {
-            element.Serialize(stream, specVersion, OpenApiFormat.Json);
+            return element.SerializeAsync(stream, specVersion, OpenApiFormat.Json, cancellationToken);
         }
 
         /// <summary>
@@ -35,10 +38,11 @@ public static void SerializeAsJson<T>(this T element, Stream stream, OpenApiSpec
         /// <param name="element">The Open API element.</param>
         /// <param name="stream">The output stream.</param>
         /// <param name="specVersion">The Open API specification version.</param>
-        public static void SerializeAsYaml<T>(this T element, Stream stream, OpenApiSpecVersion specVersion)
+        /// <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
         {
-            element.Serialize(stream, specVersion, OpenApiFormat.Yaml);
+            return element.SerializeAsync(stream, specVersion, OpenApiFormat.Yaml, cancellationToken);
         }
 
         /// <summary>
@@ -50,14 +54,16 @@ public static void SerializeAsYaml<T>(this T element, Stream stream, OpenApiSpec
         /// <param name="stream">The given stream.</param>
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="format">The output format (JSON or YAML).</param>
-        public static void Serialize<T>(
+        /// <param name="cancellationToken">The cancellation token.</param>
+        public static Task SerializeAsync<T>(
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format)
+            OpenApiFormat format,
+            CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            element.Serialize(stream, specVersion, format, null);
+            return element.SerializeAsync(stream, specVersion, format, null, cancellationToken);
         }
 
         /// <summary>
@@ -70,12 +76,14 @@ public static void Serialize<T>(
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="format">The output format (JSON or YAML).</param>
         /// <param name="settings">Provide configuration settings for controlling writing output</param>
-        public static void Serialize<T>(
+        /// <param name="cancellationToken">The cancellation token.</param>
+        public static Task SerializeAsync<T>(
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
             OpenApiFormat format,
-            OpenApiWriterSettings settings)
+            OpenApiWriterSettings settings,
+            CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
             Utils.CheckArgumentNull(stream);
@@ -88,7 +96,7 @@ public static void Serialize<T>(
                 OpenApiFormat.Yaml => new OpenApiYamlWriter(streamWriter, settings),
                 _ => throw new OpenApiException(string.Format(SRResource.OpenApiFormatNotSupported, format)),
             };
-            element.Serialize(writer, specVersion);
+            return element.SerializeAsync(writer, specVersion, cancellationToken);
         }
 
         /// <summary>
@@ -98,7 +106,8 @@ public static void Serialize<T>(
         /// <param name="element">The Open API element.</param>
         /// <param name="writer">The output writer.</param>
         /// <param name="specVersion">Version of the specification the output should conform to</param>
-        public static void Serialize<T>(this T element, IOpenApiWriter writer, OpenApiSpecVersion specVersion)
+        /// <param name="cancellationToken">The cancellation token.</param>
+        public static Task SerializeAsync<T>(this T element, IOpenApiWriter writer, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
             Utils.CheckArgumentNull(element);
@@ -122,7 +131,7 @@ public static void Serialize<T>(this T element, IOpenApiWriter writer, OpenApiSp
                     throw new OpenApiException(string.Format(SRResource.OpenApiSpecVersionNotSupported, specVersion));
             }
 
-            writer.Flush();
+            return writer.FlushAsync(cancellationToken);
         }
 
         /// <summary>
@@ -131,12 +140,14 @@ public static void Serialize<T>(this T element, IOpenApiWriter writer, OpenApiSp
         /// <typeparam name="T">the <see cref="IOpenApiSerializable"/></typeparam>
         /// <param name="element">The Open API element.</param>
         /// <param name="specVersion">The Open API specification version.</param>
-        public static string SerializeAsJson<T>(
+        /// <param name="cancellationToken">The cancellation token.</param>
+        public static Task<string> SerializeAsJsonAsync<T>(
             this T element,
-            OpenApiSpecVersion specVersion)
+            OpenApiSpecVersion specVersion,
+            CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            return element.Serialize(specVersion, OpenApiFormat.Json);
+            return element.SerializeAsync(specVersion, OpenApiFormat.Json, cancellationToken);
         }
 
         /// <summary>
@@ -145,12 +156,14 @@ public static string SerializeAsJson<T>(
         /// <typeparam name="T">the <see cref="IOpenApiSerializable"/></typeparam>
         /// <param name="element">The Open API element.</param>
         /// <param name="specVersion">The Open API specification version.</param>
-        public static string SerializeAsYaml<T>(
+        /// <param name="cancellationToken">The cancellation token.</param>
+        public static Task<string> SerializeAsYamlAsync<T>(
             this T element,
-            OpenApiSpecVersion specVersion)
+            OpenApiSpecVersion specVersion,
+            CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            return element.Serialize(specVersion, OpenApiFormat.Yaml);
+            return element.SerializeAsync(specVersion, OpenApiFormat.Yaml, cancellationToken);
         }
 
         /// <summary>
@@ -160,20 +173,26 @@ public static string SerializeAsYaml<T>(
         /// <param name="element">The Open API element.</param>
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="format">Open API document format.</param>
-        public static string Serialize<T>(
+        /// <param name="cancellationToken">The cancellation token.</param>
+        public static async Task<string> SerializeAsync<T>(
             this T element,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format)
+            OpenApiFormat format,
+            CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
             Utils.CheckArgumentNull(element);
 
             using var stream = new MemoryStream();
-            element.Serialize(stream, specVersion, format);
+            await element.SerializeAsync(stream, specVersion, format, cancellationToken).ConfigureAwait(false);
             stream.Position = 0;
 
             using var streamReader = new StreamReader(stream);
-            return streamReader.ReadToEnd();
+#if NET7_0_OR_GREATER
+            return await streamReader.ReadToEndAsync(cancellationToken).ConfigureAwait(false);
+#else
+            return await streamReader.ReadToEndAsync().ConfigureAwait(false);
+#endif
         }
     }
 }

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -83,11 +83,6 @@ public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenAp
         /// </summary>
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
-        /// <summary>
-        /// The unique hash code of the generated OpenAPI document
-        /// </summary>
-        public string HashCode => GenerateHashValue(this);
-
         /// <inheritdoc />
         public IDictionary<string, object>? Annotations { get; set; }
 
@@ -457,17 +452,17 @@ public void SetReferenceHostDocument()
         /// <summary>
         /// Takes in an OpenApi document instance and generates its hash value
         /// </summary>
-        /// <param name="doc">The OpenAPI description to hash.</param>
+        /// <param name="cancellationToken">Propagates notification that operations should be canceled.</param>
         /// <returns>The hash value.</returns>
-        public static string GenerateHashValue(OpenApiDocument doc)
+        public async Task<string> GetHashCodeAsync(CancellationToken cancellationToken = default)
         {
             using HashAlgorithm sha = SHA512.Create();
             using var cryptoStream = new CryptoStream(Stream.Null, sha, CryptoStreamMode.Write);
             using var streamWriter = new StreamWriter(cryptoStream);
 
             var openApiJsonWriter = new OpenApiJsonWriter(streamWriter, new() { Terse = true });
-            doc.SerializeAsV3(openApiJsonWriter);
-            openApiJsonWriter.Flush();
+            SerializeAsV3(openApiJsonWriter);
+            await openApiJsonWriter.FlushAsync(cancellationToken).ConfigureAwait(false);
 
             cryptoStream.FlushFinalBlock();
             var hash = sha.Hash;

src/Microsoft.OpenApi/Writers/IOpenApiWriter.cs

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System.Threading;
+using System.Threading.Tasks;
+
 namespace Microsoft.OpenApi.Writers
 {
     /// <summary>
@@ -71,6 +74,7 @@ public interface IOpenApiWriter
         /// <summary>
         /// Flush the writer.
         /// </summary>
-        void Flush();
+        /// <param name="cancellationToken">The cancellation token.</param>
+        Task FlushAsync(CancellationToken cancellationToken = default);
     }
 }

src/Microsoft.OpenApi/Writers/OpenApiWriterBase.cs

@@ -7,6 +7,8 @@
 using System.IO;
 using System.Linq;
 using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Extensions;
@@ -46,7 +48,7 @@ public abstract class OpenApiWriterBase : IOpenApiWriter
         /// Initializes a new instance of the <see cref="OpenApiWriterBase"/> class.
         /// </summary>
         /// <param name="textWriter">The text writer.</param>
-        public OpenApiWriterBase(TextWriter textWriter) : this(textWriter, null)
+        protected OpenApiWriterBase(TextWriter textWriter) : this(textWriter, null)
         {
         }
 
@@ -55,7 +57,7 @@ public OpenApiWriterBase(TextWriter textWriter) : this(textWriter, null)
         /// </summary>
         /// <param name="textWriter"></param>
         /// <param name="settings"></param>
-        public OpenApiWriterBase(TextWriter textWriter, OpenApiWriterSettings settings)
+        protected OpenApiWriterBase(TextWriter textWriter, OpenApiWriterSettings settings)
         {
             Writer = textWriter;
             Writer.NewLine = "\n";
@@ -119,12 +121,14 @@ public OpenApiWriterBase(TextWriter textWriter, OpenApiWriterSettings settings)
         /// </summary>
         public abstract void WriteRaw(string value);
 
-        /// <summary>
-        /// Flush the writer.
-        /// </summary>
-        public void Flush()
+        /// <inheritdoc/>
+        public Task FlushAsync(CancellationToken cancellationToken = default)
         {
-            Writer.Flush();
+#if NET8_OR_GREATER
+            return Writer.FlushAsync(cancellationToken);
+#else
+            return Writer.FlushAsync();
+#endif
         }
 
         /// <summary>