feat: openapiformat enum cleanup

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

@@ -43,7 +43,7 @@
         /// <summary>
         /// Implementation of the transform command
         /// </summary>
         public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILogger logger, CancellationToken cancellationToken = default)
         {
             if (string.IsNullOrEmpty(options.OpenApi) && string.IsNullOrEmpty(options.Csdl) && string.IsNullOrEmpty(options.FilterOptions?.FilterByApiManifest))
             {
@@ -55,7 +55,7 @@
                 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 @@
                 }
 
                 // 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 @@
                 }
 
                 // 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 @@
             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 @@
                     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 @@
         /// <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 @@
                     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 @@
             }
 
             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,14 +778,14 @@
             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",
                                                         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")
                 {
                     DescriptionForHuman = document.Info?.Description ?? "Description placeholder",
                     Api = new("openapi", "./openapi.json"),

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 @@
         /// <summary>
         /// Default format.
         /// </summary>
-        private OpenApiFormat _format = OpenApiFormat.Yaml;
+        private string _format = OpenApiConstants.Yaml;
 
         /// <summary>
         /// Default version.
@@ -121,7 +121,7 @@
             }
         }
 
-        public OpenApiFormat Format
+        public string Format
         {
             get => _format;
             set
@@ -166,14 +166,14 @@
 
         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
@@ -210,7 +210,7 @@
         /// The core method of the class.
         /// Runs the parsing and serializing.
         /// </summary>
         internal async Task ParseDocumentAsync()
         {
             Stream stream = null;
             try
@@ -243,7 +243,7 @@
                         : 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;
 
@@ -25,10 +26,10 @@
         /// <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, OpenApiFormat.Json, cancellationToken);
+            return element.SerializeAsync(stream, specVersion, OpenApiConstants.Json, cancellationToken);
         }
 
         /// <summary>
@@ -39,10 +40,10 @@
         /// <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, OpenApiFormat.Yaml, cancellationToken);
+            return element.SerializeAsync(stream, specVersion, OpenApiConstants.Yaml, cancellationToken);
         }
 
         /// <summary>
@@ -55,11 +56,11 @@
         /// <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,
-            OpenApiFormat format,
+            string format,
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {
@@ -81,7 +82,7 @@
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format,
+            string format,
             OpenApiWriterSettings? settings = null,
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
@@ -90,10 +91,10 @@
 
             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 @@
             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 @@
             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 async Task<string> SerializeAsync<T>(
             this T element,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format,
+            string format,
             CancellationToken cancellationToken = default)
             where T : IOpenApiSerializable
         {

test/Microsoft.OpenApi.Hidi.Tests/Services/OpenApiServiceTests.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.Tests/Models/OpenApiContactTests.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

test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs

@@ -1557,7 +1557,7 @@ public async Task SerializeDocumentWithReferenceButNoComponents()
             document.Paths["/"].Operations[HttpMethod.Get].Responses["200"].Content["application/json"].Schema = new OpenApiSchemaReference("test", document);
 
             // Act
-            var actual = await document.SerializeAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json);
+            var actual = await document.SerializeAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
 
             // Assert
             Assert.NotEmpty(actual);

test/Microsoft.OpenApi.Tests/Models/OpenApiEncodingTests.cs

@@ -22,9 +22,9 @@ public class OpenApiEncodingTests
         };
 
         [Theory]
-        [InlineData(OpenApiFormat.Json, "{ }")]
-        [InlineData(OpenApiFormat.Yaml, "{ }")]
-        public async Task SerializeBasicEncodingAsV3Works(OpenApiFormat format, string expected)
+        [InlineData(OpenApiConstants.Json, "{ }")]
+        [InlineData(OpenApiConstants.Yaml, "{ }")]
+        public async Task SerializeBasicEncodingAsV3Works(string format, string expected)
         {
             // Arrange & Act
             var actual = await BasicEncoding.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, format);

test/Microsoft.OpenApi.Tests/Models/OpenApiExternalDocsTests.cs

@@ -22,9 +22,9 @@ public class OpenApiExternalDocsTests
         #region OpenAPI V3
 
         [Theory]
-        [InlineData(OpenApiFormat.Json, "{ }")]
-        [InlineData(OpenApiFormat.Yaml, "{ }")]
-        public async Task SerializeBasicExternalDocsAsV3Works(OpenApiFormat format, string expected)
+        [InlineData(OpenApiConstants.Json, "{ }")]
+        [InlineData(OpenApiConstants.Yaml, "{ }")]
+        public async Task SerializeBasicExternalDocsAsV3Works(string format, string expected)
         {
             // Arrange & Act
             var actual = await BasicExDocs.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, format);

test/Microsoft.OpenApi.Tests/Models/OpenApiInfoTests.cs

@@ -205,7 +205,7 @@ public async Task InfoVersionShouldAcceptDateStyledAsVersions()
                 """;
 
             // Act
-            var actual = await info.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Yaml);
+            var actual = await info.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Yaml);
 
             // Assert
             actual = actual.MakeLineBreaksEnvironmentNeutral();