-
Notifications
You must be signed in to change notification settings - Fork 10k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support multiple OpenAPI documents per application #54676
Comments
would this function to include one document in another as well? var builder = WebApplication.CreateBuilder();
builder.Services.AddControllers();
builder.Services.AddOpenApi("unstable", options =>
{
options.ShouldInclude = (description, documentName) => true;
});
builder.Services.AddOpenApi("stable", options =>
{
options.ShouldInclude = (description, documentName) => description.IsDefined<StableAttribute>();
});
var app = builder.Build();
// /openapi/unstable/openapi.json
// /openapi/stable/openapi.json
app.MapOpenApi();
app.MapGet("/at/risk/for/breaking/changes", () => { });
app.MapGet("/safe/to/depend/on", [Stable] () => { }); |
@bbarry Yep, based on the setup you configured in your sample code you'd get the following documents outputted:
|
API Review Notes:
API Approved! // Assembly: Microsoft.AspNetCore.OpenApi
namespace Microsoft.Extensions.DependencyInjection;
public static class OpenApiServiceCollectionExtensions
{
+ public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName);
+ public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName, Action<OpenApiOptions> configureOptions);
} // Assembly: Microsoft.AspNetCore.OpenApi
namespace Microsoft.AspNetCore.OpenApi;
public class OpenApiOptions
{
+ public string DocumentName { get; }
+ public Func<ApiDescription, bool> ShouldInclude { get; set; } = (description) => description.GroupName == null || description.GroupName == DocumentName;
} |
@captainsafia @halter73 I haven't fully investigated what's in the redesigned open api library yet but this issue seemed like a good place to point out an important consideration that I've dealt with in the past when using aspnetcore mvc versioning combined with swashbuckle for open api spec generation. When generating separate OAS .json files for different api versions in the same project, it's an important use case that the generation be capable of putting a common api version prefix portion of the endpoint route into the OAS base url in lieu of having the api version prefix be inclued in each operation path section in the OAS. Demonstration example: [ApiController]
[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Authorize]
[Route("api/example-versioned-rest-api/v{version:apiVersion}/weather-forecasts")]
public class WeatherForecastController : ControllerBase
{
[HttpGet]
[MapsToApiVersion("1.0")]
public async Task<ActionResult<WeatherForecastsV1Response>> GetWeatherForecastsAsync(
CancellationToken cancellationToken)
{
// code for deprecated v1 response
}
[HttpGet]
[MapsToApiVersion("2.0")]
public async Task<ActionResult<WeatherForecastsV2Response>> GetWeatherForecastsAsync(
CancellationToken cancellationToken)
{
// code for v2 response
}
} Desired Output: {
"openapi": "3.0.1"
"info": { "title": "...", "version": "1.0" },
"servers": [
{ "url" : "/api/example-versioned-rest-api/v1" }
]
"paths" {
"/weather-forecasts": { ... }
}
}
{
"openapi": "3.0.1"
"info": { "title": "...", "version": "2.0" },
"servers": [
{ "url" : "/api/example-versioned-rest-api/v2" }
]
"paths" {
"/weather-forecasts": { ... }
}
} This is something that swashbuckle did not support natively and I had to write custom document filter logic to adjust for. Why this is an important use case:
|
@RyanThomas73 It looks like you are using Asp.Versioning to handle multi-version support for your APIs. Part of the challenge with this is getting all three components (Asp.Versioning + ASP.NET Core + OpenAPI document generation) to play nice with each other. IMO, the expected output you've identified above should be trivial to support with a document transformer that modifies the I'm going to close this particular issue for tracking purposes since this API has been implemented but please chime in with your scenario on the main issue over at #54598 and we can continue the discussion there. |
Background and Motivation
Users need the ability to group endpoints in the same application into different documents by various properties. This API proposal outlines how to support multiple documents in the same application using keyed services behind the scenes.
Proposed API
// Assembly: Microsoft.AspNetCore.OpenApi namespace Microsoft.AspNetCore.OpenApi; public class OpenApiOptions { + public Func<ApiDescription, string, bool> ShouldInclude { get; set; } = (description, documentName) => description.GroupName == null || description.GroupName == documentName; }
Usage Examples
Create different OpenAPI documents versioned by API description group name.
Create different OpenAPI documents for internal and public-facing APIs.
Alternative Designs
The text was updated successfully, but these errors were encountered: