Open API: Add fluent builder for registering custom backoffice OpenAPI documents

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

@@ -1,4 +1,3 @@
-using System.Text.Json.Serialization.Metadata;
 using Asp.Versioning;
 using Microsoft.AspNetCore.Mvc.Abstractions;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
@@ -69,7 +68,7 @@ protected virtual void ConfigureOpenApi(OpenApiOptions options)
         });
 
         options.ShouldInclude = ShouldInclude;
-        options.CreateSchemaReferenceId = CreateSchemaReferenceId;
+        options.CreateSchemaReferenceId = UmbracoSchemaIdGenerator.CreateSchemaReferenceId;
 
         options.AddOperationTransformer<UmbracoOperationIdTransformer>();
 
@@ -80,33 +79,6 @@ protected virtual void ConfigureOpenApi(OpenApiOptions options)
             .AddDocumentTransformer<SortTagsAndPathsTransformer>();
     }
 
-    /// <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>

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

@@ -30,6 +30,27 @@ public static IServiceCollection ReplaceOpenApiSchemaService(
         this IServiceCollection services,
         string documentName,
         string jsonOptionsName)
+        => services.ReplaceOpenApiSchemaService(
+            documentName,
+            sp => sp.GetRequiredService<IOptionsMonitor<JsonOptions>>().Get(jsonOptionsName));
+
+    /// <summary>
+    /// Replaces the internal Microsoft <c>OpenApiSchemaService</c> registration for the specified document so that schema
+    /// generation uses the <see cref="JsonOptions"/> instance produced by the supplied factory. Use this overload when
+    /// the options need to be resolved from the service provider, computed at the last moment, or built in a way that
+    /// doesn't fit the named-options lookup.
+    /// </summary>
+    /// <param name="services">The service collection.</param>
+    /// <param name="documentName">The OpenAPI document key.</param>
+    /// <param name="jsonOptionsFactory">Factory invoked when the schema service is first resolved. Receives the resolving <see cref="IServiceProvider"/> and returns the <see cref="JsonOptions"/> to use.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> for chaining.</returns>
+    /// <remarks>
+    /// Workaround for <see href="https://github.com/dotnet/aspnetcore/issues/66340">dotnet/aspnetcore#66340</see>.
+    /// </remarks>
+    public static IServiceCollection ReplaceOpenApiSchemaService(
+        this IServiceCollection services,
+        string documentName,
+        Func<IServiceProvider, JsonOptions> jsonOptionsFactory)
     {
         ServiceDescriptor descriptor = services.FirstOrDefault(sd =>
             sd.ServiceType.FullName == OpenApiSchemaServiceFullName
@@ -47,7 +68,7 @@ public static IServiceCollection ReplaceOpenApiSchemaService(
                 sp,
                 descriptor.ServiceType,
                 key,
-                Options.Create(sp.GetRequiredService<IOptionsMonitor<JsonOptions>>().Get(jsonOptionsName))));
+                Options.Create(jsonOptionsFactory(sp))));
 
         return services;
     }

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

@@ -23,12 +23,26 @@ public static IServiceCollection AddOpenApiDocumentToUi(
         this IServiceCollection services,
         string documentName,
         string? documentTitle = null)
+        => services.AddOpenApiDocumentToUi(documentName, () => documentTitle);
+
+    /// <summary>
+    /// Adds an OpenAPI document to the OpenAPI UI document selector dropdown, resolving the title lazily so
+    /// callers (such as builder-pattern helpers) can defer it until SwaggerUI options are resolved.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> instance.</param>
+    /// <param name="documentName">The name/identifier of the OpenAPI document.</param>
+    /// <param name="documentTitleFactory">Factory invoked when SwaggerUI options are resolved. Returning <c>null</c> falls back to <paramref name="documentName"/>.</param>
+    /// <returns>The <see cref="IServiceCollection"/> instance.</returns>
+    internal static IServiceCollection AddOpenApiDocumentToUi(
+        this IServiceCollection services,
+        string documentName,
+        Func<string?> documentTitleFactory)
     {
         services.AddOptions<SwaggerUIOptions>()
             .Configure<IOptions<UmbracoOpenApiOptions>>((swaggerUiOptions, openApiOptions) =>
             {
                 var openApiRoute = openApiOptions.Value.RouteTemplate.Replace("{documentName}", documentName).EnsureStartsWith("/");
-                swaggerUiOptions.SwaggerEndpoint(openApiRoute, documentTitle ?? documentName);
+                swaggerUiOptions.SwaggerEndpoint(openApiRoute, documentTitleFactory() ?? documentName);
                 swaggerUiOptions.ConfigObject.Urls = swaggerUiOptions.ConfigObject.Urls.OrderBy(x => x.Name);
             });
 

src/Umbraco.Cms.Api.Common/OpenApi/BackOfficeOpenApiDocumentBuilder.cs

@@ -0,0 +1,169 @@
+using Microsoft.AspNetCore.Http.Json;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using Umbraco.Cms.Api.Common.DependencyInjection;
+using Umbraco.Cms.Core.DependencyInjection;
+using Umbraco.Extensions;
+
+namespace Umbraco.Cms.Api.Common.OpenApi;
+
+/// <summary>
+/// Fluent builder for configuring a custom OpenAPI document.
+/// </summary>
+public sealed class BackOfficeOpenApiDocumentBuilder
+{
+    private readonly List<Action<OpenApiOptions>> _configurations = [];
+
+    private string? _title;
+    private string? _uiTitle;
+    private bool _includedInUi = true;
+    private Func<IServiceProvider, JsonOptions>? _httpJsonOptionsFactory;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BackOfficeOpenApiDocumentBuilder"/> class.
+    /// </summary>
+    /// <param name="documentName">The name of the OpenAPI document being configured.</param>
+    internal BackOfficeOpenApiDocumentBuilder(string documentName)
+        => DocumentName = documentName;
+
+    /// <summary>
+    /// Gets the name of the OpenAPI document being configured.
+    /// </summary>
+    public string DocumentName { get; }
+
+    /// <summary>
+    /// Sets the document's <c>Info.Title</c>. Also used as the UI dropdown label unless overridden via
+    /// <see cref="WithUiTitle"/>.
+    /// </summary>
+    /// <param name="title">The title to display.</param>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder WithTitle(string title)
+    {
+        _title = title;
+        return this;
+    }
+
+    /// <summary>
+    /// Overrides the UI dropdown label for this document.
+    /// </summary>
+    /// <param name="uiTitle">The label to display.</param>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder WithUiTitle(string uiTitle)
+    {
+        _uiTitle = uiTitle;
+        return this;
+    }
+
+    /// <summary>
+    /// Excludes this document from the UI dropdown.
+    /// </summary>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder ExcludeFromUi()
+    {
+        _includedInUi = false;
+        return this;
+    }
+
+    /// <summary>
+    /// Adds an <see cref="OpenApiOptions"/> configuration callback. Multiple calls compose.
+    /// </summary>
+    /// <param name="configure">Callback to configure the options.</param>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder ConfigureOpenApiOptions(Action<OpenApiOptions> configure)
+    {
+        _configurations.Add(configure);
+        return this;
+    }
+
+    /// <summary>
+    /// Sets the named <see cref="JsonOptions">Microsoft.AspNetCore.Http.Json.JsonOptions</see> used when
+    /// generating this document's schema. Use this to match the serialization conventions of the API
+    /// endpoints the document describes.
+    /// </summary>
+    /// <param name="jsonOptionsName">The name of the registered HTTP <see cref="JsonOptions"/> to apply.</param>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder WithJsonOptions(string jsonOptionsName)
+        => WithJsonOptions(sp => sp.GetRequiredService<IOptionsMonitor<JsonOptions>>().Get(jsonOptionsName));
+
+    /// <summary>
+    /// Sets the <see cref="JsonOptions">Microsoft.AspNetCore.Http.Json.JsonOptions</see> used when
+    /// generating this document's schema. Use this to match the serialization conventions of the API
+    /// endpoints the document describes.
+    /// </summary>
+    /// <param name="jsonOptions">The HTTP JSON options to apply.</param>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder WithJsonOptions(JsonOptions jsonOptions)
+        => WithJsonOptions(_ => jsonOptions);
+
+    /// <summary>
+    /// Sets a factory that produces the <see cref="JsonOptions">Microsoft.AspNetCore.Http.Json.JsonOptions</see>
+    /// used when generating this document's schema. Use this to match the serialization conventions of the
+    /// API endpoints the document describes.
+    /// </summary>
+    /// <param name="jsonOptionsFactory">Factory invoked when the schema service is first resolved.</param>
+    /// <returns>The same builder for chaining.</returns>
+    public BackOfficeOpenApiDocumentBuilder WithJsonOptions(Func<IServiceProvider, JsonOptions> jsonOptionsFactory)
+    {
+        _httpJsonOptionsFactory = jsonOptionsFactory;
+        return this;
+    }
+
+    /// <summary>
+    /// Applies the accumulated configuration to the supplied <see cref="IUmbracoBuilder"/>'s service
+    /// collection. Called by <c>AddBackOfficeOpenApiDocument</c> once the user-supplied callback returns.
+    /// </summary>
+    /// <param name="builder">The Umbraco builder to register services against.</param>
+    internal void Build(IUmbracoBuilder builder)
+    {
+        builder.Services.AddOpenApi(
+            DocumentName,
+            options =>
+            {
+                options.ShouldInclude = apiDescription =>
+                    apiDescription.ActionDescriptor.HasMapToApiAttribute(DocumentName);
+
+                options.CreateSchemaReferenceId = UmbracoSchemaIdGenerator.CreateSchemaReferenceId;
+
+                if (_title is not null)
+                {
+                    options.AddDocumentTransformer((document, _, _) =>
+                    {
+                        document.Info.Title = _title;
+                        return Task.CompletedTask;
+                    });
+                }
+
+                // Generate operation IDs using Umbraco's naming conventions.
+                options.AddOperationTransformer<UmbracoOperationIdTransformer>();
+
+                // Trim redundant JSON-equivalent MIME types (e.g. text/json, application/*+json, text/plain)
+                // that ASP.NET Core adds alongside application/json.
+                options.AddOperationTransformer<MimeTypesTransformer>();
+
+                // Mark non-nullable properties as required so generated SDKs reflect the C# nullability.
+                options.AddSchemaTransformer<RequireNonNullablePropertiesSchemaTransformer>();
+
+                // Tag actions by group name and cleanup unused tags (caused by the tag changes).
+                options
+                    .AddOperationTransformer<TagActionsByGroupNameTransformer>()
+                    .AddDocumentTransformer<TagActionsByGroupNameTransformer>()
+                    .AddDocumentTransformer<SortTagsAndPathsTransformer>();
+
+                foreach (Action<OpenApiOptions> configure in _configurations)
+                {
+                    configure(options);
+                }
+            });
+
+        if (_includedInUi)
+        {
+            builder.Services.AddOpenApiDocumentToUi(DocumentName, _uiTitle ?? _title);
+        }
+
+        if (_httpJsonOptionsFactory is not null)
+        {
+            builder.Services.ReplaceOpenApiSchemaService(DocumentName, _httpJsonOptionsFactory);
+        }
+    }
+}

src/Umbraco.Cms.Api.Common/OpenApi/MimeTypesTransformer.cs

@@ -1,5 +1,5 @@
+using System.Net.Mime;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.AspNetCore.Mvc.Formatters;
 using Microsoft.AspNetCore.OpenApi;
 using Microsoft.OpenApi;
 using Umbraco.Extensions;
@@ -12,6 +12,13 @@ namespace Umbraco.Cms.Api.Common.OpenApi;
 /// </summary>
 internal class MimeTypesTransformer : IOpenApiOperationTransformer
 {
+    private static readonly string[] _jsonEquivalentMimeTypes =
+    [
+        MediaTypeNames.Text.Plain,
+        "application/*+json",
+        "text/json"
+    ];
+
     /// <inheritdoc/>
     public Task TransformAsync(
         OpenApiOperation operation,
@@ -40,7 +47,7 @@ public Task TransformAsync(
             }
             else
             {
-                RemoveNonJsonMimeTypes(requestContent);
+                RemoveJsonEquivalentMimeTypes(requestContent);
             }
         }
 
@@ -49,20 +56,20 @@ public Task TransformAsync(
         {
             if (response is OpenApiResponse openApiResponse)
             {
-                RemoveNonJsonMimeTypes(openApiResponse.Content);
+                RemoveJsonEquivalentMimeTypes(openApiResponse.Content);
             }
         }
 
         return Task.CompletedTask;
     }
 
-    private static void RemoveNonJsonMimeTypes(IDictionary<string, OpenApiMediaType>? content)
+    private static void RemoveJsonEquivalentMimeTypes(IDictionary<string, OpenApiMediaType>? content)
     {
-        if (content?.ContainsKey("application/json") != true)
+        if (content?.ContainsKey(MediaTypeNames.Application.Json) != true)
         {
             return;
         }
 
-        content.RemoveAll(r => r.Key != "application/json");
+        content.RemoveAll(r => _jsonEquivalentMimeTypes.Contains(r.Key, StringComparer.OrdinalIgnoreCase));
     }
 }