feat: openapiformat enum cleanup (#2326)

* feat: openapiformat enum cleanup

* align string options

Co-authored-by: Vincent Biret <[email protected]>

* resolve PR comments

---------

Co-authored-by: Vincent Biret <[email protected]>

Author: Michael-Wamae

README.md

@@ -88,7 +88,7 @@ var stream = await httpClient.GetStreamAsync("main/examples/v3.0/petstore.yaml")
 var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic);
 
 // Write V2 as JSON
-var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json);
+var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
 
 ```
 

docs/upgrade-guide-2.md

@@ -487,10 +487,24 @@ The `SerializeAs()` method simplifies serialization scenarios, making it easier
 
 ```csharp
 OpenApiDocument document = new OpenApiDocument();
-string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json);
+string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Json);
 
 ```
 
+### Use OpenApiConstants string Instead of OpenApiFormat Enum
+
+OpenApiConstants are now used instead of OpenApiFormat enums.
+
+**Example:**
+
+```csharp
+// Before (1.6)
+var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json); 
+
+// After (2.0)
+var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
+```
+
 ### Bug Fixes
 
 ## Serialization of References

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -55,7 +55,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
                 if (options.Output == null)
                 {
 #pragma warning disable CA1308 // Normalize strings to uppercase
-                    var extension = options.OpenApiFormat?.GetDisplayName().ToLowerInvariant();
+                    var extension = options.OpenApiFormat?.ToLowerInvariant();
                     var inputExtension = !string.IsNullOrEmpty(extension) ? string.Concat(".", extension) 
                         : GetInputPathExtension(options.OpenApi, options.Csdl);
 
@@ -73,7 +73,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
                 }
 
                 // Default to yaml and OpenApiVersion 3_1 during csdl to OpenApi conversion
-                var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
+                var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
                 var openApiVersion = options.Version != null ? TryParseOpenApiSpecVersion(options.Version) : OpenApiSpecVersion.OpenApi3_1;
 
                 // If ApiManifest is provided, set the referenced OpenAPI document
@@ -92,7 +92,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
                 }
 
                 // Load OpenAPI document
-                var document = await GetOpenApiAsync(options, openApiFormat.GetDisplayName(), logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
+                var document = await GetOpenApiAsync(options, openApiFormat, logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
 
                 if (options.FilterOptions != null && document is not null)
                 {
@@ -189,7 +189,7 @@ private static OpenApiDocument ApplyFilters(HidiOptions options, ILogger logger,
             return document;
         }
 
-        private static async Task WriteOpenApiAsync(HidiOptions options, OpenApiFormat openApiFormat, OpenApiSpecVersion openApiVersion, OpenApiDocument document, ILogger logger, CancellationToken cancellationToken)
+        private static async Task WriteOpenApiAsync(HidiOptions options, string openApiFormat, OpenApiSpecVersion openApiVersion, OpenApiDocument document, ILogger logger, CancellationToken cancellationToken)
         {
             using (logger.BeginScope("Output"))
             {
@@ -202,11 +202,12 @@ private static async Task WriteOpenApiAsync(HidiOptions options, OpenApiFormat o
                     InlineLocalReferences = options.InlineLocal,
                     InlineExternalReferences = options.InlineExternal
                 };
-
-                IOpenApiWriter writer = openApiFormat switch
+#pragma warning disable CA1308
+                IOpenApiWriter writer = openApiFormat.ToLowerInvariant() switch
+#pragma warning restore CA1308
                 {
-                    OpenApiFormat.Json => options.TerseOutput ? new(textWriter, settings, options.TerseOutput) : new OpenApiJsonWriter(textWriter, settings, false),
-                    OpenApiFormat.Yaml => new OpenApiYamlWriter(textWriter, settings),
+                    OpenApiConstants.Json => options.TerseOutput ? new(textWriter, settings, options.TerseOutput) : new OpenApiJsonWriter(textWriter, settings, false),
+                    OpenApiConstants.Yaml => new OpenApiYamlWriter(textWriter, settings),
                     _ => throw new ArgumentException("Unknown format"),
                 };
 
@@ -560,10 +561,10 @@ SecurityException or
         /// <param name="input"></param>
         /// <param name="logger"></param>
         /// <returns></returns>
-        private static OpenApiFormat GetOpenApiFormat(string input, ILogger logger)
+        private static string GetOpenApiFormat(string input, ILogger logger)
         {
             logger.LogTrace("Getting the OpenApi format");
-            return !input.StartsWith("http", StringComparison.OrdinalIgnoreCase) && Path.GetExtension(input) == ".json" ? OpenApiFormat.Json : OpenApiFormat.Yaml;
+            return !input.StartsWith("http", StringComparison.OrdinalIgnoreCase) && Path.GetExtension(input) == ".json" ? OpenApiConstants.Json : OpenApiConstants.Yaml;
         }
 
         private static string GetInputPathExtension(string? openapi = null, string? csdl = null)
@@ -590,8 +591,8 @@ private static string GetInputPathExtension(string? openapi = null, string? csdl
                     throw new ArgumentException("Please input a file path or URL");
                 }
 
-                var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
-                var document = await GetOpenApiAsync(options, openApiFormat.GetDisplayName(), logger, null, cancellationToken).ConfigureAwait(false);
+                var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
+                var document = await GetOpenApiAsync(options, openApiFormat, logger, null, cancellationToken).ConfigureAwait(false);
                 if (document is not null)
                 {
                     using (logger.BeginScope("Creating diagram"))
@@ -754,10 +755,10 @@ internal static async Task PluginManifestAsync(HidiOptions options, ILogger logg
             }
 
             var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) 
-                ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
+                ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
 
             // Load OpenAPI document
-            var document = await GetOpenApiAsync(options, openApiFormat.GetDisplayName(), logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
+            var document = await GetOpenApiAsync(options, openApiFormat, logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
 
             cancellationToken.ThrowIfCancellationRequested();
 
@@ -777,7 +778,7 @@ internal static async Task PluginManifestAsync(HidiOptions options, ILogger logg
             options.TerseOutput = true;
             if (document is not null)
             {
-                await WriteOpenApiAsync(options, OpenApiFormat.Json, OpenApiSpecVersion.OpenApi3_1, document, logger, cancellationToken).ConfigureAwait(false);
+                await WriteOpenApiAsync(options, OpenApiConstants.Json, OpenApiSpecVersion.OpenApi3_1, document, logger, cancellationToken).ConfigureAwait(false);
 
                 // Create OpenAIPluginManifest from ApiDependency and OpenAPI document
                 var manifest = new OpenAIPluginManifest(document.Info.Title ?? "Title",

src/Microsoft.OpenApi.Hidi/Options/CommandOptions.cs

@@ -16,7 +16,7 @@ internal class CommandOptions
         public readonly Option<bool> CleanOutputOption = new("--clean-output", "Overwrite an existing file");
         public readonly Option<string> VersionOption = new("--version", "OpenAPI specification version");
         public readonly Option<string> MetadataVersionOption = new("--metadata-version", "Graph metadata version to use.");
-        public readonly Option<OpenApiFormat?> FormatOption = new("--format", "File format");
+        public readonly Option<string> FormatOption = new("--format", "File format");
         public readonly Option<bool> TerseOutputOption = new("--terse-output", "Produce terse json output");
         public readonly Option<string> SettingsFileOption = new("--settings-path", "The configuration file with CSDL conversion settings.");
         public readonly Option<LogLevel> LogLevelOption = new("--log-level", () => LogLevel.Information, "The log level to use when logging messages to the main output.");

src/Microsoft.OpenApi.Hidi/Options/HidiOptions.cs

@@ -20,7 +20,7 @@ internal class HidiOptions
         public bool CleanOutput { get; set; }
         public string? Version { get; set; }
         public string? MetadataVersion { get; set; }
-        public OpenApiFormat? OpenApiFormat { get; set; }
+        public string? OpenApiFormat { get; set; }
         public bool TerseOutput { get; set; }
         public IConfiguration? SettingsConfig { get; set; }
         public LogLevel LogLevel { get; set; }

src/Microsoft.OpenApi.Workbench/MainModel.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System;
@@ -43,7 +43,7 @@ public class MainModel : INotifyPropertyChanged
         /// <summary>
         /// Default format.
         /// </summary>
-        private OpenApiFormat _format = OpenApiFormat.Yaml;
+        private string _format = OpenApiConstants.Yaml;
 
         /// <summary>
         /// Default version.
@@ -121,7 +121,7 @@ public string RenderTime
             }
         }
 
-        public OpenApiFormat Format
+        public string Format
         {
             get => _format;
             set
@@ -166,14 +166,14 @@ public OpenApiSpecVersion Version
 
         public bool IsYaml
         {
-            get => Format == OpenApiFormat.Yaml;
-            set => Format = value ? OpenApiFormat.Yaml : Format;
+            get => Format == OpenApiConstants.Yaml;
+            set => Format = value ? OpenApiConstants.Yaml : Format;
         }
 
         public bool IsJson
         {
-            get => Format == OpenApiFormat.Json;
-            set => Format = value ? OpenApiFormat.Json : Format;
+            get => Format == OpenApiConstants.Json;
+            set => Format = value ? OpenApiConstants.Json : Format;
         }
 
         public bool IsV2_0
@@ -243,7 +243,7 @@ internal async Task ParseDocumentAsync()
                         : new("file://" + Path.GetDirectoryName(_inputFile) + "/");
                 }
 
-                var readResult = await OpenApiDocument.LoadAsync(stream, Format.GetDisplayName().ToLowerInvariant(), settings);
+                var readResult = await OpenApiDocument.LoadAsync(stream, Format.ToLowerInvariant(), settings);
                 var document = readResult.Document;
                 var context = readResult.Diagnostic;
 

src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs

@@ -7,6 +7,7 @@
 using System.Threading.Tasks;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Properties;
 using Microsoft.OpenApi.Writers;
 
@@ -28,7 +29,7 @@ public static class OpenApiSerializableExtensions
         public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            return element.SerializeAsync(stream, specVersion, OpenApiFormat.Json, cancellationToken);
+            return element.SerializeAsync(stream, specVersion, OpenApiConstants.Json, cancellationToken);
         }
 
         /// <summary>
@@ -42,7 +43,7 @@ public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenAp
         public static Task SerializeAsYamlAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            return element.SerializeAsync(stream, specVersion, OpenApiFormat.Yaml, cancellationToken);
+            return element.SerializeAsync(stream, specVersion, OpenApiConstants.Yaml, cancellationToken);
         }
 
         /// <summary>
@@ -59,7 +60,7 @@ public static Task SerializeAsync<T>(
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format,
+            string format,
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
@@ -81,7 +82,7 @@ public static Task SerializeAsync<T>(
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format,
+            string format,
             OpenApiWriterSettings? settings = null,
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
@@ -90,10 +91,10 @@ public static Task SerializeAsync<T>(
 
             var streamWriter = new FormattingStreamWriter(stream, CultureInfo.InvariantCulture);
 
-            IOpenApiWriter writer = format switch
+            IOpenApiWriter writer = format.ToLowerInvariant() switch
             {
-                OpenApiFormat.Json => new OpenApiJsonWriter(streamWriter, settings, false),
-                OpenApiFormat.Yaml => new OpenApiYamlWriter(streamWriter, settings),
+                OpenApiConstants.Json => new OpenApiJsonWriter(streamWriter, settings, false),
+                OpenApiConstants.Yaml => new OpenApiYamlWriter(streamWriter, settings),
                 _ => throw new OpenApiException(string.Format(SRResource.OpenApiFormatNotSupported, format)),
             };
             return element.SerializeAsync(writer, specVersion, cancellationToken);
@@ -147,7 +148,7 @@ public static Task<string> SerializeAsJsonAsync<T>(
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            return element.SerializeAsync(specVersion, OpenApiFormat.Json, cancellationToken);
+            return element.SerializeAsync(specVersion, OpenApiConstants.Json, cancellationToken);
         }
 
         /// <summary>
@@ -163,7 +164,7 @@ public static Task<string> SerializeAsYamlAsync<T>(
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
-            return element.SerializeAsync(specVersion, OpenApiFormat.Yaml, cancellationToken);
+            return element.SerializeAsync(specVersion, OpenApiConstants.Yaml, cancellationToken);
         }
 
         /// <summary>
@@ -177,7 +178,7 @@ public static Task<string> SerializeAsYamlAsync<T>(
         public static async Task<string> SerializeAsync<T>(
             this T element,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format,
+            string format,
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {

src/Microsoft.OpenApi/OpenApiFormat.cs

@@ -261,7 +261,7 @@ public async Task TransformCommandConvertsOpenApiWithDefaultOutputNameAndSwitchF
                 OpenApi = Path.Combine("UtilityFiles", "SampleOpenApi.yml"),
                 CleanOutput = true,
                 Version = "3.0",
-                OpenApiFormat = OpenApiFormat.Yaml,
+                OpenApiFormat = OpenApiConstants.Yaml,
                 TerseOutput = false,
                 InlineLocal = false,
                 InlineExternal = false,
@@ -296,7 +296,7 @@ public async Task TransformToPowerShellCompliantOpenApiAsync()
                 OpenApi = Path.Combine("UtilityFiles", "SampleOpenApi.yml"),
                 CleanOutput = true,
                 Version = "3.0",
-                OpenApiFormat = OpenApiFormat.Yaml,
+                OpenApiFormat = OpenApiConstants.Yaml,
                 TerseOutput = false,
                 InlineLocal = false,
                 InlineExternal = false,

test/Microsoft.OpenApi.Hidi.Tests/Services/OpenApiServiceTests.cs

@@ -28,13 +28,13 @@ public class OpenApiContactTests
         };
 
         [Theory]
-        [InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json, "{ }")]
-        [InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json, "{ }")]
-        [InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Yaml, "{ }")]
-        [InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Yaml, "{ }")]
+        [InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Json, "{ }")]
+        [InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json, "{ }")]
+        [InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Yaml, "{ }")]
+        [InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Yaml, "{ }")]
         public async Task SerializeBasicContactWorks(
             OpenApiSpecVersion version,
-            OpenApiFormat format,
+            string format,
             string expected)
         {
             // Arrange & Act