Skip to content

Commit 0623dc7

Browse files
sander1095sander1095
committed
Update v10 examples so all projects work
REQUIRED: - Replace duplicate code with AddOpenApi() calls per version with 1 "AddOpenApi" call from Asp.Versioning itself - Change GroupNameFormat from 4 V's to 3 V's to prevent exception about keyed services. OPTIONAL: - Call "AddMvc" for controllers. Without it, things seem to work, but I believe it's an integral part. All the examples from the asp.versioning repo have it, so I believe this should, too.
1 parent d9a7b53 commit 0623dc7

5 files changed

Lines changed: 50 additions & 28 deletions

File tree

‎v10/controllers/queryheader-versioning/Program.cs‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
var builder = WebApplication.CreateBuilder(args);
44

5-
builder.Services.AddOpenApi("v1");
6-
builder.Services.AddOpenApi("v2");
7-
85
builder.Services.AddControllers();
96

107
builder.Services.AddApiVersioning(options =>
@@ -48,12 +45,20 @@
4845
// note: the specified format code will format the version as "'v'major[.minor][-status]"
4946
// More information: https://github.com/dotnet/aspnet-api-versioning/wiki/Version-Format#custom-api-version-format-strings
5047
// Without this, the OpenAPI document will not generate correctly.
51-
options.GroupNameFormat = "'v'VVVV";
52-
});
48+
options.GroupNameFormat = "'v'VVV";
49+
})
50+
.AddMvc()
51+
// You must call "AddOpenApi" after "AddApiVersioning" to ensure you use Asp.Versioning's variant.
52+
// This variant of "AddOpenApi" is required to properly integrate with API versioning and generate versioned OpenAPI documents.
53+
.AddOpenApi();
5354

5455
var app = builder.Build();
5556

56-
app.MapOpenApi();
57+
// WithDocumentPerVersion() is an extension method provided by the Asp.Versioning.OpenApi package.
58+
// It configures the OpenAPI endpoint to generate a separate document for each API version.
59+
// This allows clients to retrieve documentation specific to the version of the API they are using.
60+
// This approach is preferable compared to having to call "services.AddOpenApi()" multiple times for each version, which can lead to maintenance issues and potential misconfigurations when adding new versions.
61+
app.MapOpenApi().WithDocumentPerVersion();
5762

5863
app.MapControllers();
5964

‎v10/controllers/url-versioning/Program.cs‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
var builder = WebApplication.CreateBuilder(args);
44

5-
builder.Services.AddOpenApi("v1");
6-
builder.Services.AddOpenApi("v2");
7-
85
builder.Services.AddControllers();
96

107
builder.Services.AddApiVersioning(options =>
@@ -31,11 +28,19 @@
3128
// note: this option is only necessary when versioning by url segment. the SubstitutionFormat
3229
// can also be used to control the format of the API version in route templates
3330
options.SubstituteApiVersionInUrl = true;
34-
});
31+
})
32+
.AddMvc()
33+
// You must call "AddOpenApi" after "AddApiVersioning" to ensure you use Asp.Versioning's variant.
34+
// This variant of "AddOpenApi" is required to properly integrate with API versioning and generate versioned OpenAPI documents.
35+
.AddOpenApi();
3536

3637
var app = builder.Build();
3738

38-
app.MapOpenApi();
39+
// WithDocumentPerVersion() is an extension method provided by the Asp.Versioning.OpenApi package.
40+
// It configures the OpenAPI endpoint to generate a separate document for each API version.
41+
// This allows clients to retrieve documentation specific to the version of the API they are using.
42+
// This approach is preferable compared to having to call "services.AddOpenApi()" multiple times for each version, which can lead to maintenance issues and potential misconfigurations when adding new versions.
43+
app.MapOpenApi().WithDocumentPerVersion();
3944

4045
app.MapControllers();
4146

‎v10/minimal-api/aot-versioning/Program.cs‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,6 @@
88
options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
99
});
1010

11-
builder.Services.AddOpenApi("v1");
12-
builder.Services.AddOpenApi("v2");
13-
1411
builder.Services.AddApiVersioning(options =>
1512
{
1613
// Supported/deprecated API versions will be reported in response headers
@@ -52,12 +49,19 @@
5249
// note: the specified format code will format the version as "'v'major[.minor][-status]"
5350
// More information: https://github.com/dotnet/aspnet-api-versioning/wiki/Version-Format#custom-api-version-format-strings
5451
// Without this, the OpenAPI document will not generate correctly.
55-
options.GroupNameFormat = "'v'VVVV";
56-
});
52+
options.GroupNameFormat = "'v'VVV";
53+
})
54+
// You must call "AddOpenApi" after "AddApiVersioning" to ensure you use Asp.Versioning's variant.
55+
// This variant of "AddOpenApi" is required to properly integrate with API versioning and generate versioned OpenAPI documents.
56+
.AddOpenApi();
5757

5858
var app = builder.Build();
5959

60-
app.MapOpenApi();
60+
// WithDocumentPerVersion() is an extension method provided by the Asp.Versioning.OpenApi package.
61+
// It configures the OpenAPI endpoint to generate a separate document for each API version.
62+
// This allows clients to retrieve documentation specific to the version of the API they are using.
63+
// This approach is preferable compared to having to call "services.AddOpenApi()" multiple times for each version, which can lead to maintenance issues and potential misconfigurations when adding new versions.
64+
app.MapOpenApi().WithDocumentPerVersion();
6165

6266
var usersApi = app.NewVersionedApi("Users");
6367
var scoresApi = app.NewVersionedApi("Scores");

‎v10/minimal-api/queryheader-versioning/Program.cs‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
var builder = WebApplication.CreateBuilder(args);
44

5-
builder.Services.AddOpenApi("v1");
6-
builder.Services.AddOpenApi("v2");
7-
85
builder.Services.AddApiVersioning(options =>
96
{
107
// Supported/deprecated API versions will be reported in response headers
@@ -46,12 +43,19 @@
4643
// note: the specified format code will format the version as "'v'major[.minor][-status]"
4744
// More information: https://github.com/dotnet/aspnet-api-versioning/wiki/Version-Format#custom-api-version-format-strings
4845
// Without this, the OpenAPI document will not generate correctly.
49-
options.GroupNameFormat = "'v'VVVV";
50-
});
46+
options.GroupNameFormat = "'v'VVV";
47+
})
48+
// You must call "AddOpenApi" after "AddApiVersioning" to ensure you use Asp.Versioning's variant.
49+
// This variant of "AddOpenApi" is required to properly integrate with API versioning and generate versioned OpenAPI documents.
50+
.AddOpenApi();
5151

5252
var app = builder.Build();
5353

54-
app.MapOpenApi();
54+
// WithDocumentPerVersion() is an extension method provided by the Asp.Versioning.OpenApi package.
55+
// It configures the OpenAPI endpoint to generate a separate document for each API version.
56+
// This allows clients to retrieve documentation specific to the version of the API they are using.
57+
// This approach is preferable compared to having to call "services.AddOpenApi()" multiple times for each version, which can lead to maintenance issues and potential misconfigurations when adding new versions.
58+
app.MapOpenApi().WithDocumentPerVersion();
5559

5660
var usersApi = app.NewVersionedApi("Users");
5761
var scoresApi = app.NewVersionedApi("Scores");

‎v10/minimal-api/url-versioning/Program.cs‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
var builder = WebApplication.CreateBuilder(args);
44

5-
builder.Services.AddOpenApi("v1");
6-
builder.Services.AddOpenApi("v2");
7-
85
builder.Services.AddApiVersioning(options =>
96
{
107
// Supported/deprecated API versions will be reported in response headers
@@ -29,11 +26,18 @@
2926
// note: this option is only necessary when versioning by url segment. the SubstitutionFormat
3027
// can also be used to control the format of the API version in route templates
3128
options.SubstituteApiVersionInUrl = true;
32-
});
29+
})
30+
// You must call "AddOpenApi" after "AddApiVersioning" to ensure you use Asp.Versioning's variant.
31+
// This variant of "AddOpenApi" is required to properly integrate with API versioning and generate versioned OpenAPI documents.
32+
.AddOpenApi();
3333

3434
var app = builder.Build();
3535

36-
app.MapOpenApi();
36+
// WithDocumentPerVersion() is an extension method provided by the Asp.Versioning.OpenApi package.
37+
// It configures the OpenAPI endpoint to generate a separate document for each API version.
38+
// This allows clients to retrieve documentation specific to the version of the API they are using.
39+
// This approach is preferable compared to having to call "services.AddOpenApi()" multiple times for each version, which can lead to maintenance issues and potential misconfigurations when adding new versions.
40+
app.MapOpenApi().WithDocumentPerVersion();
3741

3842
var usersApi = app.NewVersionedApi("Users");
3943
var scoresApi = app.NewVersionedApi("Scores");

0 commit comments

Comments
 (0)