Correct way to use AddOpenApi with API versioning

[marcominerva]

Hi!

In the OpenApi.Extensions.cs file from eShop, I see this code to define the available API versions with AddOpenApi:

if (apiVersioning is not null)
{
    // the default format will just be ApiVersion.ToString(); for example, 1.0.
    // this will format the version as "'v'major[.minor][-status]"
    var versioned = apiVersioning.AddApiExplorer(options => options.GroupNameFormat = "'v'VVV");
    string[] versions = ["v1"];
    foreach (var description in versions)
    {
        builder.Services.AddOpenApi(description, options =>
        {
            options.ApplyApiVersionInfo(openApi.GetRequiredValue("Document:Title"), openApi.GetRequiredValue("Document:Description"));
            options.ApplyAuthorizationChecks([.. scopes.Keys]);
            options.ApplySecuritySchemeDefinitions();
            options.ApplyOperationDefaultValues();
        });
    }
}

In particular, I refer to the line:

string[] versions = ["v1"];

My question is: is there a way to dynamically infer the available API versions at runtime?

[martincostello]

I don't think there is at the moment, based on this block of code:

aspnetcore/src/OpenApi/src/Services/OpenApiDocumentProvider.cs

Lines 53 to 64 in f2ea31d

	/// <summary>
	/// Provides all document names that are currently managed in the application.
	/// </summary>
	public IEnumerable<string> GetDocumentNames()
	{
	// Keyed services lack an API to resolve all registered keys.
	// We use the service provider to resolve an internal type.
	// This type tracks registered document names.
	// See https://github.com/dotnet/runtime/issues/100105 for more info.
	var documentServices = serviceProvider.GetServices<NamedService<OpenApiDocumentService>>();
	return documentServices.Select(docService => docService.Name);
	}

[felipementel]

@marcominerva

builder.Services.AddOpenApi("v1", options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;

    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info.Contact = new OpenApiContact
        {
            Name = "Felipe Augusto, MVP",
            Url = new Uri("https://www.youtube.com/@D.E.P.L.O.Y"),
        };
        document.Info.License = new OpenApiLicense
        {
            Name = "MIT",
            Url = new Uri("https://opensource.org/licenses/MIT")
        };
        return Task.CompletedTask;
    });
});

builder.Services.AddOpenApi("v2", options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;

    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info.Contact = new OpenApiContact
        {
            Name = "Felipe Augusto, MVP",
            Url = new Uri("https://www.youtube.com/@D.E.P.L.O.Y"),
        };
        document.Info.License = new OpenApiLicense
        {
            Name = "MIT",
            Url = new Uri("https://opensource.org/licenses/MIT")
        };
        return Task.CompletedTask;
    });
});

Now you can see the both paths at /openapi/v1.json and /openapi/v2.json