Skip to content

Commit 19ffd13

Browse files
Michael-Wamaebaywet
Michael-Wamae
and
baywet
authored
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]>
1 parent bf9954a commit 19ffd13

19 files changed

+88
-98
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ var stream = await httpClient.GetStreamAsync("main/examples/v3.0/petstore.yaml")
8888
var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic);
8989

9090
// Write V2 as JSON
91-
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json);
91+
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
9292

9393
```
9494

‎docs/upgrade-guide-2.md

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -487,10 +487,24 @@ The `SerializeAs()` method simplifies serialization scenarios, making it easier
487487

488488
```csharp
489489
OpenApiDocument document = new OpenApiDocument();
490-
string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json);
490+
string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Json);
491491

492492
```
493493

494+
### Use OpenApiConstants string Instead of OpenApiFormat Enum
495+
496+
OpenApiConstants are now used instead of OpenApiFormat enums.
497+
498+
**Example:**
499+
500+
```csharp
501+
// Before (1.6)
502+
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json);
503+
504+
// After (2.0)
505+
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
506+
```
507+
494508
### Bug Fixes
495509

496510
## Serialization of References

‎src/Microsoft.OpenApi.Hidi/OpenApiService.cs

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
5555
if (options.Output == null)
5656
{
5757
#pragma warning disable CA1308 // Normalize strings to uppercase
58-
var extension = options.OpenApiFormat?.GetDisplayName().ToLowerInvariant();
58+
var extension = options.OpenApiFormat?.ToLowerInvariant();
5959
var inputExtension = !string.IsNullOrEmpty(extension) ? string.Concat(".", extension)
6060
: GetInputPathExtension(options.OpenApi, options.Csdl);
6161

@@ -73,7 +73,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
7373
}
7474

7575
// Default to yaml and OpenApiVersion 3_1 during csdl to OpenApi conversion
76-
var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
76+
var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
7777
var openApiVersion = options.Version != null ? TryParseOpenApiSpecVersion(options.Version) : OpenApiSpecVersion.OpenApi3_1;
7878

7979
// If ApiManifest is provided, set the referenced OpenAPI document
@@ -92,7 +92,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
9292
}
9393

9494
// Load OpenAPI document
95-
var document = await GetOpenApiAsync(options, openApiFormat.GetDisplayName(), logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
95+
var document = await GetOpenApiAsync(options, openApiFormat, logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
9696

9797
if (options.FilterOptions != null && document is not null)
9898
{
@@ -189,7 +189,7 @@ private static OpenApiDocument ApplyFilters(HidiOptions options, ILogger logger,
189189
return document;
190190
}
191191

192-
private static async Task WriteOpenApiAsync(HidiOptions options, OpenApiFormat openApiFormat, OpenApiSpecVersion openApiVersion, OpenApiDocument document, ILogger logger, CancellationToken cancellationToken)
192+
private static async Task WriteOpenApiAsync(HidiOptions options, string openApiFormat, OpenApiSpecVersion openApiVersion, OpenApiDocument document, ILogger logger, CancellationToken cancellationToken)
193193
{
194194
using (logger.BeginScope("Output"))
195195
{
@@ -202,11 +202,12 @@ private static async Task WriteOpenApiAsync(HidiOptions options, OpenApiFormat o
202202
InlineLocalReferences = options.InlineLocal,
203203
InlineExternalReferences = options.InlineExternal
204204
};
205-
206-
IOpenApiWriter writer = openApiFormat switch
205+
#pragma warning disable CA1308
206+
IOpenApiWriter writer = openApiFormat.ToLowerInvariant() switch
207+
#pragma warning restore CA1308
207208
{
208-
OpenApiFormat.Json => options.TerseOutput ? new(textWriter, settings, options.TerseOutput) : new OpenApiJsonWriter(textWriter, settings, false),
209-
OpenApiFormat.Yaml => new OpenApiYamlWriter(textWriter, settings),
209+
OpenApiConstants.Json => options.TerseOutput ? new(textWriter, settings, options.TerseOutput) : new OpenApiJsonWriter(textWriter, settings, false),
210+
OpenApiConstants.Yaml => new OpenApiYamlWriter(textWriter, settings),
210211
_ => throw new ArgumentException("Unknown format"),
211212
};
212213

@@ -560,10 +561,10 @@ SecurityException or
560561
/// <param name="input"></param>
561562
/// <param name="logger"></param>
562563
/// <returns></returns>
563-
private static OpenApiFormat GetOpenApiFormat(string input, ILogger logger)
564+
private static string GetOpenApiFormat(string input, ILogger logger)
564565
{
565566
logger.LogTrace("Getting the OpenApi format");
566-
return !input.StartsWith("http", StringComparison.OrdinalIgnoreCase) && Path.GetExtension(input) == ".json" ? OpenApiFormat.Json : OpenApiFormat.Yaml;
567+
return !input.StartsWith("http", StringComparison.OrdinalIgnoreCase) && Path.GetExtension(input) == ".json" ? OpenApiConstants.Json : OpenApiConstants.Yaml;
567568
}
568569

569570
private static string GetInputPathExtension(string? openapi = null, string? csdl = null)
@@ -590,8 +591,8 @@ private static string GetInputPathExtension(string? openapi = null, string? csdl
590591
throw new ArgumentException("Please input a file path or URL");
591592
}
592593

593-
var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
594-
var document = await GetOpenApiAsync(options, openApiFormat.GetDisplayName(), logger, null, cancellationToken).ConfigureAwait(false);
594+
var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
595+
var document = await GetOpenApiAsync(options, openApiFormat, logger, null, cancellationToken).ConfigureAwait(false);
595596
if (document is not null)
596597
{
597598
using (logger.BeginScope("Creating diagram"))
@@ -754,10 +755,10 @@ internal static async Task PluginManifestAsync(HidiOptions options, ILogger logg
754755
}
755756

756757
var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi)
757-
? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
758+
? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
758759

759760
// Load OpenAPI document
760-
var document = await GetOpenApiAsync(options, openApiFormat.GetDisplayName(), logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
761+
var document = await GetOpenApiAsync(options, openApiFormat, logger, options.MetadataVersion, cancellationToken).ConfigureAwait(false);
761762

762763
cancellationToken.ThrowIfCancellationRequested();
763764

@@ -777,7 +778,7 @@ internal static async Task PluginManifestAsync(HidiOptions options, ILogger logg
777778
options.TerseOutput = true;
778779
if (document is not null)
779780
{
780-
await WriteOpenApiAsync(options, OpenApiFormat.Json, OpenApiSpecVersion.OpenApi3_1, document, logger, cancellationToken).ConfigureAwait(false);
781+
await WriteOpenApiAsync(options, OpenApiConstants.Json, OpenApiSpecVersion.OpenApi3_1, document, logger, cancellationToken).ConfigureAwait(false);
781782

782783
// Create OpenAIPluginManifest from ApiDependency and OpenAPI document
783784
var manifest = new OpenAIPluginManifest(document.Info.Title ?? "Title",

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ internal class CommandOptions
1616
public readonly Option<bool> CleanOutputOption = new("--clean-output", "Overwrite an existing file");
1717
public readonly Option<string> VersionOption = new("--version", "OpenAPI specification version");
1818
public readonly Option<string> MetadataVersionOption = new("--metadata-version", "Graph metadata version to use.");
19-
public readonly Option<OpenApiFormat?> FormatOption = new("--format", "File format");
19+
public readonly Option<string> FormatOption = new("--format", "File format");
2020
public readonly Option<bool> TerseOutputOption = new("--terse-output", "Produce terse json output");
2121
public readonly Option<string> SettingsFileOption = new("--settings-path", "The configuration file with CSDL conversion settings.");
2222
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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ internal class HidiOptions
2020
public bool CleanOutput { get; set; }
2121
public string? Version { get; set; }
2222
public string? MetadataVersion { get; set; }
23-
public OpenApiFormat? OpenApiFormat { get; set; }
23+
public string? OpenApiFormat { get; set; }
2424
public bool TerseOutput { get; set; }
2525
public IConfiguration? SettingsConfig { get; set; }
2626
public LogLevel LogLevel { get; set; }

‎src/Microsoft.OpenApi.Workbench/MainModel.cs

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) Microsoft Corporation. All rights reserved.
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
22
// Licensed under the MIT license.
33

44
using System;
@@ -43,7 +43,7 @@ public class MainModel : INotifyPropertyChanged
4343
/// <summary>
4444
/// Default format.
4545
/// </summary>
46-
private OpenApiFormat _format = OpenApiFormat.Yaml;
46+
private string _format = OpenApiConstants.Yaml;
4747

4848
/// <summary>
4949
/// Default version.
@@ -121,7 +121,7 @@ public string RenderTime
121121
}
122122
}
123123

124-
public OpenApiFormat Format
124+
public string Format
125125
{
126126
get => _format;
127127
set
@@ -166,14 +166,14 @@ public OpenApiSpecVersion Version
166166

167167
public bool IsYaml
168168
{
169-
get => Format == OpenApiFormat.Yaml;
170-
set => Format = value ? OpenApiFormat.Yaml : Format;
169+
get => Format == OpenApiConstants.Yaml;
170+
set => Format = value ? OpenApiConstants.Yaml : Format;
171171
}
172172

173173
public bool IsJson
174174
{
175-
get => Format == OpenApiFormat.Json;
176-
set => Format = value ? OpenApiFormat.Json : Format;
175+
get => Format == OpenApiConstants.Json;
176+
set => Format = value ? OpenApiConstants.Json : Format;
177177
}
178178

179179
public bool IsV2_0
@@ -243,7 +243,7 @@ internal async Task ParseDocumentAsync()
243243
: new("file://" + Path.GetDirectoryName(_inputFile) + "/");
244244
}
245245

246-
var readResult = await OpenApiDocument.LoadAsync(stream, Format.GetDisplayName().ToLowerInvariant(), settings);
246+
var readResult = await OpenApiDocument.LoadAsync(stream, Format.ToLowerInvariant(), settings);
247247
var document = readResult.Document;
248248
var context = readResult.Diagnostic;
249249

‎src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
using System.Threading.Tasks;
88
using Microsoft.OpenApi.Exceptions;
99
using Microsoft.OpenApi.Interfaces;
10+
using Microsoft.OpenApi.Models;
1011
using Microsoft.OpenApi.Properties;
1112
using Microsoft.OpenApi.Writers;
1213

@@ -28,7 +29,7 @@ public static class OpenApiSerializableExtensions
2829
public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
2930
where T : IOpenApiSerializable
3031
{
31-
return element.SerializeAsync(stream, specVersion, OpenApiFormat.Json, cancellationToken);
32+
return element.SerializeAsync(stream, specVersion, OpenApiConstants.Json, cancellationToken);
3233
}
3334

3435
/// <summary>
@@ -42,7 +43,7 @@ public static Task SerializeAsJsonAsync<T>(this T element, Stream stream, OpenAp
4243
public static Task SerializeAsYamlAsync<T>(this T element, Stream stream, OpenApiSpecVersion specVersion, CancellationToken cancellationToken = default)
4344
where T : IOpenApiSerializable
4445
{
45-
return element.SerializeAsync(stream, specVersion, OpenApiFormat.Yaml, cancellationToken);
46+
return element.SerializeAsync(stream, specVersion, OpenApiConstants.Yaml, cancellationToken);
4647
}
4748

4849
/// <summary>
@@ -59,7 +60,7 @@ public static Task SerializeAsync<T>(
5960
this T element,
6061
Stream stream,
6162
OpenApiSpecVersion specVersion,
62-
OpenApiFormat format,
63+
string format,
6364
CancellationToken cancellationToken = default)
6465
where T : IOpenApiSerializable
6566
{
@@ -81,7 +82,7 @@ public static Task SerializeAsync<T>(
8182
this T element,
8283
Stream stream,
8384
OpenApiSpecVersion specVersion,
84-
OpenApiFormat format,
85+
string format,
8586
OpenApiWriterSettings? settings = null,
8687
CancellationToken cancellationToken = default)
8788
where T : IOpenApiSerializable
@@ -90,10 +91,10 @@ public static Task SerializeAsync<T>(
9091

9192
var streamWriter = new FormattingStreamWriter(stream, CultureInfo.InvariantCulture);
9293

93-
IOpenApiWriter writer = format switch
94+
IOpenApiWriter writer = format.ToLowerInvariant() switch
9495
{
95-
OpenApiFormat.Json => new OpenApiJsonWriter(streamWriter, settings, false),
96-
OpenApiFormat.Yaml => new OpenApiYamlWriter(streamWriter, settings),
96+
OpenApiConstants.Json => new OpenApiJsonWriter(streamWriter, settings, false),
97+
OpenApiConstants.Yaml => new OpenApiYamlWriter(streamWriter, settings),
9798
_ => throw new OpenApiException(string.Format(SRResource.OpenApiFormatNotSupported, format)),
9899
};
99100
return element.SerializeAsync(writer, specVersion, cancellationToken);
@@ -147,7 +148,7 @@ public static Task<string> SerializeAsJsonAsync<T>(
147148
CancellationToken cancellationToken = default)
148149
where T : IOpenApiSerializable
149150
{
150-
return element.SerializeAsync(specVersion, OpenApiFormat.Json, cancellationToken);
151+
return element.SerializeAsync(specVersion, OpenApiConstants.Json, cancellationToken);
151152
}
152153

153154
/// <summary>
@@ -163,7 +164,7 @@ public static Task<string> SerializeAsYamlAsync<T>(
163164
CancellationToken cancellationToken = default)
164165
where T : IOpenApiSerializable
165166
{
166-
return element.SerializeAsync(specVersion, OpenApiFormat.Yaml, cancellationToken);
167+
return element.SerializeAsync(specVersion, OpenApiConstants.Yaml, cancellationToken);
167168
}
168169

169170
/// <summary>
@@ -177,7 +178,7 @@ public static Task<string> SerializeAsYamlAsync<T>(
177178
public static async Task<string> SerializeAsync<T>(
178179
this T element,
179180
OpenApiSpecVersion specVersion,
180-
OpenApiFormat format,
181+
string format,
181182
CancellationToken cancellationToken = default)
182183
where T : IOpenApiSerializable
183184
{

‎src/Microsoft.OpenApi/OpenApiFormat.cs

Lines changed: 0 additions & 21 deletions
This file was deleted.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ public async Task TransformCommandConvertsOpenApiWithDefaultOutputNameAndSwitchF
261261
OpenApi = Path.Combine("UtilityFiles", "SampleOpenApi.yml"),
262262
CleanOutput = true,
263263
Version = "3.0",
264-
OpenApiFormat = OpenApiFormat.Yaml,
264+
OpenApiFormat = OpenApiConstants.Yaml,
265265
TerseOutput = false,
266266
InlineLocal = false,
267267
InlineExternal = false,
@@ -296,7 +296,7 @@ public async Task TransformToPowerShellCompliantOpenApiAsync()
296296
OpenApi = Path.Combine("UtilityFiles", "SampleOpenApi.yml"),
297297
CleanOutput = true,
298298
Version = "3.0",
299-
OpenApiFormat = OpenApiFormat.Yaml,
299+
OpenApiFormat = OpenApiConstants.Yaml,
300300
TerseOutput = false,
301301
InlineLocal = false,
302302
InlineExternal = false,

‎test/Microsoft.OpenApi.Tests/Models/OpenApiContactTests.cs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,13 @@ public class OpenApiContactTests
2828
};
2929

3030
[Theory]
31-
[InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json, "{ }")]
32-
[InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json, "{ }")]
33-
[InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Yaml, "{ }")]
34-
[InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Yaml, "{ }")]
31+
[InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Json, "{ }")]
32+
[InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json, "{ }")]
33+
[InlineData(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Yaml, "{ }")]
34+
[InlineData(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Yaml, "{ }")]
3535
public async Task SerializeBasicContactWorks(
3636
OpenApiSpecVersion version,
37-
OpenApiFormat format,
37+
string format,
3838
string expected)
3939
{
4040
// Arrange & Act

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1557,7 +1557,7 @@ public async Task SerializeDocumentWithReferenceButNoComponents()
15571557
document.Paths["/"].Operations[HttpMethod.Get].Responses["200"].Content["application/json"].Schema = new OpenApiSchemaReference("test", document);
15581558

15591559
// Act
1560-
var actual = await document.SerializeAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json);
1560+
var actual = await document.SerializeAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
15611561

15621562
// Assert
15631563
Assert.NotEmpty(actual);

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,9 @@ public class OpenApiEncodingTests
2222
};
2323

2424
[Theory]
25-
[InlineData(OpenApiFormat.Json, "{ }")]
26-
[InlineData(OpenApiFormat.Yaml, "{ }")]
27-
public async Task SerializeBasicEncodingAsV3Works(OpenApiFormat format, string expected)
25+
[InlineData(OpenApiConstants.Json, "{ }")]
26+
[InlineData(OpenApiConstants.Yaml, "{ }")]
27+
public async Task SerializeBasicEncodingAsV3Works(string format, string expected)
2828
{
2929
// Arrange & Act
3030
var actual = await BasicEncoding.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, format);

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,9 @@ public class OpenApiExternalDocsTests
2222
#region OpenAPI V3
2323

2424
[Theory]
25-
[InlineData(OpenApiFormat.Json, "{ }")]
26-
[InlineData(OpenApiFormat.Yaml, "{ }")]
27-
public async Task SerializeBasicExternalDocsAsV3Works(OpenApiFormat format, string expected)
25+
[InlineData(OpenApiConstants.Json, "{ }")]
26+
[InlineData(OpenApiConstants.Yaml, "{ }")]
27+
public async Task SerializeBasicExternalDocsAsV3Works(string format, string expected)
2828
{
2929
// Arrange & Act
3030
var actual = await BasicExDocs.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, format);

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ public async Task InfoVersionShouldAcceptDateStyledAsVersions()
205205
""";
206206

207207
// Act
208-
var actual = await info.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Yaml);
208+
var actual = await info.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Yaml);
209209

210210
// Assert
211211
actual = actual.MakeLineBreaksEnvironmentNeutral();

0 commit comments

Comments
 (0)