Open API: Use Microsoft.AspNetCore.OpenApi for Open API document generation

Directory.Packages.props

@@ -14,6 +14,7 @@
   <!-- Microsoft packages -->
   <ItemGroup>
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.2" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.1" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="10.0.1" />
@@ -76,7 +77,7 @@
     <PackageVersion Include="Serilog.Sinks.Map" Version="2.0.0" />
     <PackageVersion Include="SixLabors.ImageSharp" Version="3.1.12" />
     <PackageVersion Include="SixLabors.ImageSharp.Web" Version="3.2.0" />
-    <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.0.1" />
+    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.1" />
   </ItemGroup>
   <!-- Transitive pinned versions (only required because our direct dependencies have vulnerable versions of transitive dependencies) -->
   <ItemGroup>
@@ -88,4 +89,4 @@
     <!-- TODO (V19): Remove these pinned dependencies when the Markdown dependency is removed. -->
     <PackageVersion Include="System.Text.RegularExpressions" Version="4.3.1" />
   </ItemGroup>
-</Project>
+</Project>

src/Umbraco.Cms.Api.Common/Configuration/ConfigureDefaultApiOptions.cs

@@ -0,0 +1,47 @@
+using System.Reflection;
+using Asp.Versioning;
+using Microsoft.AspNetCore.Mvc.Abstractions;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Controllers;
+using Umbraco.Cms.Api.Common.OpenApi;
+
+namespace Umbraco.Cms.Api.Common.Configuration;
+
+/// <summary>
+/// Configures the OpenAPI options for the Default API.
+/// </summary>
+public class ConfigureDefaultApiOptions : ConfigureUmbracoOpenApiOptionsBase
+{
+    /// <inheritdoc />
+    protected override string ApiName => DefaultApiConfiguration.ApiName;
+
+    /// <inheritdoc />
+    protected override string ApiTitle => "Default API";
+
+    /// <inheritdoc />
+    protected override string ApiVersion => "Latest";
+
+    /// <inheritdoc />
+    protected override string ApiDescription => "All endpoints not defined under specific APIs";
+
+    /// <inheritdoc />
+    protected override bool ShouldInclude(ApiDescription apiDescription)
+    {
+        // Exclude controllers with ExcludeFromDefaultOpenApiDocumentAttribute
+        if (apiDescription.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor
+            && controllerActionDescriptor.ControllerTypeInfo.GetCustomAttribute<ExcludeFromDefaultOpenApiDocumentAttribute>() is not null)
+        {
+            return false;
+        }
+
+        // Include if explicitly mapped to this document
+        if (base.ShouldInclude(apiDescription))
+        {
+            return true;
+        }
+
+        // Include endpoints not explicitly assigned to another document
+        ApiVersionMetadata apiVersionMetadata = apiDescription.ActionDescriptor.GetApiVersionMetadata();
+        return string.IsNullOrEmpty(apiVersionMetadata.Name);
+    }
+}

src/Umbraco.Cms.Api.Common/Configuration/ConfigureUmbracoOpenApiOptionsBase.cs

@@ -0,0 +1,129 @@
+using System.Text.Json.Serialization.Metadata;
+using Asp.Versioning;
+using Microsoft.AspNetCore.Mvc.Abstractions;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Controllers;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi;
+using Umbraco.Cms.Api.Common.OpenApi;
+using Umbraco.Extensions;
+
+namespace Umbraco.Cms.Api.Common.Configuration;
+
+/// <summary>
+/// Base class for configuring OpenAPI options for Umbraco APIs.
+/// </summary>
+public abstract class ConfigureUmbracoOpenApiOptionsBase : IConfigureNamedOptions<OpenApiOptions>
+{
+    /// <summary>
+    ///  Gets the name/identifier of the API to configure.
+    /// </summary>
+    protected abstract string ApiName { get; }
+
+    /// <summary>
+    ///  Gets the name/identifier of the API to configure.
+    /// </summary>
+    protected abstract string ApiTitle { get; }
+
+    /// <summary>
+    ///  Gets the version of the API to configure.
+    /// </summary>
+    protected abstract string ApiVersion { get; }
+
+    /// <summary>
+    ///  Gets the description of the API to configure.
+    /// </summary>
+    protected abstract string ApiDescription { get; }
+
+    /// <inheritdoc />
+    public void Configure(OpenApiOptions options) => Configure(Options.DefaultName, options);
+
+    /// <inheritdoc />
+    public void Configure(string? name, OpenApiOptions options)
+    {
+        if (name != ApiName)
+        {
+            return;
+        }
+
+        ConfigureOpenApi(options);
+    }
+
+    /// <summary>
+    /// Configure the OpenAPI options for the specified API.
+    /// </summary>
+    /// <param name="options">The <see cref="OpenApiOptions"/> instance to configure.</param>
+    protected virtual void ConfigureOpenApi(OpenApiOptions options)
+    {
+        options.AddDocumentTransformer((document, _, _) =>
+        {
+            document.Info = new OpenApiInfo
+            {
+                Title = ApiTitle,
+                Version = ApiVersion,
+                Description = ApiDescription,
+            };
+            document.Servers?.Clear();
+            return Task.CompletedTask;
+        });
+
+        options.ShouldInclude = ShouldInclude;
+        options.CreateSchemaReferenceId = CreateSchemaReferenceId;
+
+        options.AddOperationTransformer<UmbracoOperationIdTransformer>();
+
+        // Tag actions by group name and cleanup unused tags (caused by the tag changes)
+        options
+            .AddOperationTransformer<TagActionsByGroupNameTransformer>()
+            .AddDocumentTransformer<TagActionsByGroupNameTransformer>()
+            .AddDocumentTransformer<SortTagsAndPathsTransformer>();
+
+        options.AddSchemaTransformer<RequireNonNullablePropertiesSchemaTransformer>();
+        options.AddSchemaTransformer<FixFileReturnTypesTransformer>();
+    }
+
+    /// <summary>
+    /// Creates a schema reference ID for the given JSON type info.
+    /// Returns null for types that should be inlined, the default schema ID for non-Umbraco types,
+    /// or a generated schema ID for Umbraco types.
+    /// </summary>
+    /// <param name="jsonTypeInfo">The JSON type info to create a schema reference ID for.</param>
+    /// <returns>The schema reference ID, or null if the type should be inlined.</returns>
+    internal static string? CreateSchemaReferenceId(JsonTypeInfo jsonTypeInfo)
+    {
+        // Ensure that only types that would normally be included in the schema generation are given a schema reference ID.
+        // Otherwise, we should return null to inline them.
+        var defaultSchemaReferenceId = OpenApiOptions.CreateDefaultSchemaReferenceId(jsonTypeInfo);
+        if (defaultSchemaReferenceId is null)
+        {
+            return null;
+        }
+
+        Type targetType = Nullable.GetUnderlyingType(jsonTypeInfo.Type) ?? jsonTypeInfo.Type;
+
+        if (targetType.Namespace?.StartsWith("Umbraco.Cms") is not true)
+        {
+            return defaultSchemaReferenceId;
+        }
+
+        return UmbracoSchemaIdGenerator.Generate(targetType);
+    }
+
+    /// <summary>
+    /// Determines whether the specified API description should be included in this OpenAPI document.
+    /// </summary>
+    /// <param name="apiDescription">The API description to evaluate.</param>
+    /// <returns><c>true</c> if the endpoint should be included; otherwise, <c>false</c>.</returns>
+    protected virtual bool ShouldInclude(ApiDescription apiDescription)
+    {
+        if (apiDescription.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor
+            && controllerActionDescriptor.HasMapToApiAttribute(ApiName))
+        {
+            return true;
+        }
+
+        ApiVersionMetadata apiVersionMetadata = apiDescription.ActionDescriptor.GetApiVersionMetadata();
+        return apiVersionMetadata.Name == ApiName;
+    }
+}

src/Umbraco.Cms.Api.Common/DependencyInjection/UmbracoBuilderApiExtensions.cs

@@ -1,33 +1,87 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Options;
+using Swashbuckle.AspNetCore.SwaggerUI;
 using Umbraco.Cms.Api.Common.Configuration;
 using Umbraco.Cms.Api.Common.OpenApi;
 using Umbraco.Cms.Api.Common.Serialization;
+using Umbraco.Cms.Core;
 using Umbraco.Cms.Core.DependencyInjection;
+using Umbraco.Cms.Core.Hosting;
 using Umbraco.Cms.Web.Common.ApplicationBuilder;
+using Umbraco.Extensions;
+using IHostingEnvironment = Umbraco.Cms.Core.Hosting.IHostingEnvironment;
 
 namespace Umbraco.Cms.Api.Common.DependencyInjection;
 
 public static class UmbracoBuilderApiExtensions
 {
     public static IUmbracoBuilder AddUmbracoApiOpenApiUI(this IUmbracoBuilder builder)
     {
-        if (builder.Services.Any(x => !x.IsKeyedService && x.ImplementationType == typeof(OperationIdSelector)))
+        if (builder.Services.Any(x => !x.IsKeyedService && x.ImplementationType == typeof(UmbracoJsonTypeInfoResolver)))
         {
             return builder;
         }
 
-        builder.Services.AddSwaggerGen();
-        builder.Services.ConfigureOptions<ConfigureUmbracoSwaggerGenOptions>();
+        builder.Services.AddOptions<UmbracoOpenApiOptions>()
+            .Configure<IHostingEnvironment, IWebHostEnvironment>((options, hostingEnv, webHostEnv) =>
+            {
+                options.Enabled = webHostEnv.IsProduction() is false;
+                var backOfficePath = hostingEnv.GetBackOfficePath().TrimStart(Constants.CharArrays.ForwardSlash);
+                options.RouteTemplate = $"{backOfficePath}/openapi/{{documentName}}.json";
+                options.UiRoutePrefix = $"{backOfficePath}/openapi";
+            });
+        builder.Services.AddUmbracoApi<ConfigureDefaultApiOptions>(DefaultApiConfiguration.ApiName, "Default API");
         builder.Services.AddSingleton<IUmbracoJsonTypeInfoResolver, UmbracoJsonTypeInfoResolver>();
-        builder.Services.AddSingleton<IOperationIdSelector, OperationIdSelector>();
-        builder.Services.AddSingleton<IOperationIdHandler, OperationIdHandler>();
-        builder.Services.AddSingleton<ISchemaIdSelector, SchemaIdSelector>();
-        builder.Services.AddSingleton<ISchemaIdHandler, SchemaIdHandler>();
-        builder.Services.AddSingleton<ISubTypesSelector, SubTypesSelector>();
-        builder.Services.AddSingleton<ISubTypesHandler, SubTypesHandler>();
-        builder.Services.AddSingleton<IDocumentInclusionSelector, DocumentInclusionSelector>();
-        builder.Services.Configure<UmbracoPipelineOptions>(options => options.AddFilter(new SwaggerRouteTemplatePipelineFilter("UmbracoApiCommon")));
+        builder.Services.Configure<UmbracoPipelineOptions>(options => options.AddFilter(new OpenApiRouteTemplatePipelineFilter("UmbracoApiCommon")));
 
         return builder;
     }
+
+    /// <summary>
+    /// Adds and configures an Umbraco API with OpenAPI documentation.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> instance.</param>
+    /// <param name="apiName">The name/identifier of the API.</param>
+    /// <param name="apiTitle">The title of the API.</param>
+    /// <typeparam name="TConfigureOptions">The type used to configure the OpenAPI options.</typeparam>
+    /// <returns>The <see cref="IServiceCollection"/> instance.</returns>
+    public static IServiceCollection AddUmbracoApi<TConfigureOptions>(
+        this IServiceCollection services,
+        string apiName,
+        string apiTitle)
+        where TConfigureOptions : ConfigureUmbracoOpenApiOptionsBase
+    {
+        services.AddOpenApi(apiName);
+        services.ConfigureOptions<TConfigureOptions>();
+
+        services.AddOpenApiDocumentToUi(apiName, apiTitle);
+
+        return services;
+    }
+
+    /// <summary>
+    /// Adds an OpenAPI document to the OpenAPI UI document selector dropdown.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> instance.</param>
+    /// <param name="documentName">The name/identifier of the OpenAPI document.</param>
+    /// <param name="documentTitle">The title to display in the UI dropdown. Defaults to <paramref name="documentName"/> if not specified.</param>
+    /// <returns>The <see cref="IServiceCollection"/> instance.</returns>
+    public static IServiceCollection AddOpenApiDocumentToUi(
+        this IServiceCollection services,
+        string documentName,
+        string? documentTitle = null)
+    {
+        services.AddOptions<SwaggerUIOptions>()
+            .Configure<IOptions<UmbracoOpenApiOptions>>((swaggerUiOptions, openApiOptions) =>
+            {
+                var openApiRoute = openApiOptions.Value.RouteTemplate.Replace("{documentName}", documentName).EnsureStartsWith("/");
+                swaggerUiOptions.SwaggerEndpoint(openApiRoute, documentTitle ?? documentName);
+                swaggerUiOptions.ConfigObject.Urls = swaggerUiOptions.ConfigObject.Urls.OrderBy(x => x.Name);
+            });
+
+        return services;
+    }
 }