Swagger with .Net 5 REST API.
I have an API with hundreds of methods that necessitates the use of grouping related APIs together. At the same time, I need to start work on a V2 version of my API. I have spent hours trying different approaches to implement versioning AND grouping without success.
I have several controllers, some for V1 and some for V2. Can someone offer a complete example?
Before jumping into a solution, let me qualify a few points:
ApiDescription.GroupName to collate APIs in a single document per group, which maps to the dropdown in UI. Changing this behavior is possible, but non-trivial.ApiDescription.GroupName to a formatted API version value if not otherwise set so that APIs are grouped by version. Prior to 4.1, [ApiExplorerSettings(GroupName="...")] was ignored and overwritten.At the end of the day, you are asking for two grouping dimensions: category and API version. Unfortunately, the API Explorer, OpenAPI/Swagger UI, and Swashbuckle only intrinsically support one. Any form of hierarchy is not supported out-of-the-box. There a couple of ways you can get around this:
group name and API version as a single dimensionGroupName back the way you want (This approach is not recommended)There might be more options, but these are the most sensible. While it might not be what you're hoping for, given the limitations to work with, #3 is the most straight forward to implement. It would look like this:
public class SubgroupDescriptionProvider : IApiDescriptionProvider
{
private readonly IOptions<ApiExplorerOptions> options;
public SubgroupDescriptionProvider(IOptions<ApiExplorerOptions> options)
=> this.options = options;
// Execute after DefaultApiVersionDescriptionProvider.OnProvidersExecuted
public int Order => -1;
public void OnProvidersExecuting(ApiDescriptionProviderContext context) { }
public void OnProvidersExecuted(ApiDescriptionProviderContext context)
{
var format = options.Value.GroupNameFormat;
var culture = CultureInfo.CurrentCulture;
var results = context.Results;
var newResults = new List<ApiDescription>(capacity: results.Count);
for (var i = 0; i < results.Count; i++)
{
var result = results[i];
var apiVersion = result.GetApiVersion();
var versionGroupName = apiVersion.ToString(format, culture);
// [ApiExplorerSettings(GroupName="...")] was NOT set so
// nothing else to do
if (result.GroupName == versionGroupName)
{
continue;
}
// must be using [ApiExplorerSettings(GroupName="...")] so
// concatenate it with the formatted API version
result.GroupName += " " + versionGroupName;
// optional: add version grouping as well
// note: this works because the api description will appear in
// multiple, but different, documents
var newResult = result.Clone();
newResult.GroupName = versionGroupName;
newResults.Add(newResult);
}
newResults.ForEach(results.Add);
}
}
You then register this with DI using:
services.TryAddEnumerable(
ServiceDescriptor.Transient<IApiDescriptionProvider, SubgroupDescriptionProvider>());
If you use both sets of grouping, then you'll get multiple OpenAPI documents.
By API Version (default)
├─ v1
│ ├─ /utility
│ └─ /not-utility
└─ v2
├─ /utility
└─ /not-utility
By Group Name + API Version
├─ Utilities v1
│ └─ /utility
├─ Not Utilities v1
│ └─ /not-utility
├─ Utilities v2
│ └─ /utility
└─ Not Utilities v2
└─ /not-utility
If your versioning policy is something like N-2, then the list should be reasonable. It's a product of group * version, so the list will depend on how many groups and versions you ultimately have.
Having a true, two dimensional hierarchy should be technically feasible, but I've never done it nor known anyone willing to put the effort in to make it happen. The solution would be pretty specific your set of APIs.
Use the below code in program.cs (.net 6), If you are using .net 5(or below version) use this code in strartup.cs
services.AddVersionedApiExplorer(options =>
{
options.GroupNameFormat = "'v'VV";
options.SubstituteApiVersionInUrl = true;
});
services.AddSwaggerGen(options =>
{
options.DocInclusionPredicate((documentName, apiDescription) =>
{
var actionApiVersionModel = apiDescription.ActionDescriptor.GetApiVersionModel();
var apiExplorerSettingsAttribute = (ApiExplorerSettingsAttribute)apiDescription.ActionDescriptor.EndpointMetadata.First(x => x.GetType().Equals(typeof(ApiExplorerSettingsAttribute)));
if (actionApiVersionModel == null)
{
return true;
}
if (actionApiVersionModel.DeclaredApiVersions.Any())
{
return actionApiVersionModel.DeclaredApiVersions.Any(v =>
$"{apiExplorerSettingsAttribute.GroupName}v{v}" == documentName);
}
return actionApiVersionModel.ImplementedApiVersions.Any(v =>
$"{apiExplorerSettingsAttribute.GroupName}v{v}" == documentName);
});
var apiVersionDescriptionProvider = services.BuildServiceProvider().GetService<IApiVersionDescriptionProvider>();
foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
{
options.SwaggerDoc($"Orders{description.GroupName}", new OpenApiInfo
{
Title = "Example Service",
Description = "Example Service -- Backend Service Project",
Version = description.ApiVersion.ToString(),
});
options.SwaggerDoc($"Payments{description.GroupName}", new OpenApiInfo
{
Title = "Example Service",
Description = "Example Service -- Backend Service Project",
Version = description.ApiVersion.ToString(),
});
// Orders & Payments are the groupNames, above ex: out put will be : swagger/OrdersV1.0/swagger.json ( if you select Orders from the swagger definition dropdown)
// If you select Payments => output : swagger/PaymentsV1.0/swagger.json
}
//var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI(
swaggerOptions =>
{
foreach (var description in provider.ApiVersionDescriptions)
{
swaggerOptions.SwaggerEndpoint($"{swagger/Orders{description.GroupName}/swagger.json",$"Orders {description.GroupName.ToUpperInvariant()}" );
swaggerOptions.SwaggerEndpoint($"{swagger/Payments{description.GroupName}/swagger.json", $"Payments {description.GroupName.ToUpperInvariant()}");
}
});
Controller //V1 // example controller 1:
[ApiVersion("1.0")]
[ApiController]
[ApiExplorerSettings(GroupName = "Orders")]
[Route("api/v{version:apiVersion}/[controller]")]
public class OrdersController : ControllerBase
// example controller 2:
[ApiVersion("1.0")]
[ApiController]
[ApiExplorerSettings(GroupName = "Payments")]
[Route("api/v{version:apiVersion}/[controller]")]
public class PaymentsController : ControllerBase
