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

CLAUDE.md

@@ -46,7 +46,8 @@ Enterprise-grade CMS built on .NET 10.0. This repository contains 21 production
 - **ASP.NET Core** - Web framework
 - **Entity Framework Core** - Modern ORM
 - **OpenIddict** - OAuth 2.0/OpenID Connect authentication
-- **Swashbuckle** - OpenAPI/Swagger documentation
+- **Microsoft.AspNetCore.OpenApi** - OpenAPI document generation
+- **Swashbuckle.AspNetCore.SwaggerUI** - Swagger UI for API documentation
 - **Lucene.NET** - Full-text search via Examine
 - **ImageSharp** - Image processing
 
@@ -368,10 +369,10 @@ public interface IMyService
 
 ```xml
 <!-- Individual projects reference WITHOUT version -->
-<PackageReference Include="Swashbuckle.AspNetCore" />
+<PackageReference Include="Microsoft.AspNetCore.OpenApi" />
 
 <!-- Versions defined in Directory.Packages.props -->
-<PackageVersion Include="Swashbuckle.AspNetCore" Version="6.5.0" />
+<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
 ```
 
 ### Build Configuration
@@ -417,7 +418,8 @@ All APIs use **OpenIddict** (OAuth 2.0/OpenID Connect):
 APIs use `Asp.Versioning.Mvc`:
 - Management API: `/umbraco/management/api/v{version}/*`
 - Delivery API: `/umbraco/delivery/api/v{version}/*`
-- OpenAPI/Swagger docs per version
+- OpenAPI docs: `/umbraco/openapi/management.json`, `/umbraco/openapi/delivery.json`
+- Swagger UI: `/umbraco/openapi/`
 
 ### Updating `OpenApi.json` (Management API)
 

Directory.Packages.props

@@ -15,6 +15,8 @@
   <!-- Microsoft packages -->
   <ItemGroup>
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="10.0.6" />
+    <!-- When updating this version, also update templates/UmbracoExtension/Umbraco.Extension.csproj -->
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.6" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.0.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.0.0" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.6" />
@@ -78,8 +80,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" />
-    <!-- When updating this version, also update templates/UmbracoExtension/Umbraco.Extension.csproj -->
-    <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.1.7" />
+    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />
   </ItemGroup>
   <!-- Transitive pinned versions (only required because our direct dependencies have vulnerable versions of transitive dependencies) -->
   <ItemGroup>

src/Umbraco.Cms.Api.Common/CLAUDE.md

@@ -13,7 +13,8 @@ Shared infrastructure for Umbraco CMS REST APIs (Management and Delivery).
 ### Key Technologies
 
 - **ASP.NET Core** - Web framework
-- **Swashbuckle** - OpenAPI/Swagger documentation generation
+- **Microsoft.AspNetCore.OpenApi** - OpenAPI document generation
+- **Swashbuckle.AspNetCore.SwaggerUI** - Swagger UI for browsing API documentation
 - **OpenIddict** - OAuth 2.0/OpenID Connect authentication
 - **Asp.Versioning** - API versioning
 - **System.Text.Json** - Polymorphic JSON serialization
@@ -27,14 +28,18 @@ Shared infrastructure for Umbraco CMS REST APIs (Management and Delivery).
 
 ```
 Umbraco.Cms.Api.Common/
-├── OpenApi/                    # Schema/Operation ID handlers for Swagger
-│   ├── SchemaIdHandler.cs     # Generates schema IDs (e.g., "PagedUserModel")
-│   ├── OperationIdHandler.cs  # Generates operation IDs
-│   └── SubTypesHandler.cs     # Polymorphism support
+├── OpenApi/                    # OpenAPI transformers and schema generators
+│   ├── UmbracoSchemaIdGenerator.cs         # Generates schema IDs (e.g., "PagedUserModel")
+│   ├── UmbracoOperationIdTransformer.cs    # Generates operation IDs
+│   ├── SortTagsAndPathsTransformer.cs      # Sorts OpenAPI tags and paths
+│   ├── TagActionsByGroupNameTransformer.cs # Tags operations by controller group
+│   ├── FixFileReturnTypesTransformer.cs    # Fixes file return type schemas
+│   ├── RequireNonNullablePropertiesSchemaTransformer.cs # Schema nullability
+│   └── OpenApiRouteTemplatePipelineFilter.cs # Adds OpenAPI endpoints
 ├── Serialization/              # JSON type resolution
 │   └── UmbracoJsonTypeInfoResolver.cs
 ├── Configuration/              # Options configuration
-│   ├── ConfigureUmbracoSwaggerGenOptions.cs
+│   ├── ConfigureUmbracoOpenApiOptionsBase.cs
 │   └── ConfigureOpenIddict.cs
 ├── DependencyInjection/        # Service registration
 │   ├── UmbracoBuilderApiExtensions.cs
@@ -47,9 +52,8 @@ Umbraco.Cms.Api.Common/
 
 ### Design Patterns
 
-1. **Strategy Pattern** - `ISchemaIdHandler`, `IOperationIdHandler` (extensible via inheritance)
-2. **Builder Pattern** - `ProblemDetailsBuilder` for fluent error responses
-3. **Options Pattern** - All configuration via `IConfigureOptions<T>`
+1. **Builder Pattern** - `ProblemDetailsBuilder` for fluent error responses
+2. **Options Pattern** - All configuration via `IConfigureOptions<T>`
 
 ---
 
@@ -61,36 +65,25 @@ See "Quick Reference" section at bottom for common commands.
 
 ## 3. Key Patterns
 
-### Virtual Handlers for Extensibility
+### Schema ID Generation (OpenApi/UmbracoSchemaIdGenerator.cs)
 
-Handlers are intentionally virtual to allow consuming APIs to override:
+Static utility class that generates OpenAPI schema IDs following Umbraco's naming conventions:
 
 ```csharp
-// NOTE: Left unsealed on purpose, so it is extendable.
-public class SchemaIdHandler : ISchemaIdHandler
-{
-    public virtual bool CanHandle(Type type) { }
-    public virtual string Handle(Type type) { }
-}
-```
-
-**Why**: Management and Delivery APIs can customize schema/operation ID generation.
-
-### Schema ID Sanitization (OpenApi/SchemaIdHandler.cs:24-29, 32)
-
-```csharp
-// Add "Model" suffix to avoid TypeScript name clashes (lines 24-29)
+// Add "Model" suffix to avoid TypeScript name clashes
 if (name.EndsWith("Model") == false)
 {
     // because some models names clash with common classes in TypeScript (i.e. Document),
     // we need to add a "Model" postfix to all models
     name = $"{name}Model";
 }
 
-// Remove invalid characters to prevent OpenAPI generation errors (line 32)
+// Remove invalid characters to prevent OpenAPI generation errors
 return Regex.Replace(name, @"[^\w]", string.Empty);
 ```
 
+**Generic Type Handling**: `PagedViewModel<RelationItemViewModel>` becomes `PagedRelationItemModel`
+
 ### Polymorphic Deserialization (Serialization/UmbracoJsonTypeInfoResolver.cs:29-35)
 
 ```csharp
@@ -116,9 +109,12 @@ if (type.IsInterface is false)
 dotnet test tests/Umbraco.Tests.Integration/
 
 # Verify OpenAPI generation
-# 1. Run Management API
-# 2. Navigate to /umbraco/swagger/
+# 1. Run the application: dotnet run --project src/Umbraco.Web.UI
+# 2. Navigate to /umbraco/openapi/ for Swagger UI
 # 3. Check schema IDs and operation IDs
+# OpenAPI JSON documents available at:
+#   - /umbraco/openapi/management.json (Management API)
+#   - /umbraco/openapi/delivery.json (Delivery API)
 ```
 
 **Focus areas when testing**:
@@ -207,49 +203,24 @@ catch (NotSupportedException exception)
 
 **Issue**: Type names like `Document` clash with TypeScript built-ins.
 
-**Solution**: Add "Model" suffix (OpenApi/SchemaIdHandler.cs:24-29)
+**Solution**: `UmbracoSchemaIdGenerator` adds "Model" suffix to all schema names.
 
 ### Generic Type Handling
 
 **Issue**: `PagedViewModel<T>` needs flattened schema name.
 
-**Solution** (OpenApi/SchemaIdHandler.cs:41-50):
-```csharp
-private string HandleGenerics(string name, Type type)
-{
-    if (!type.IsGenericType)
-        return name;
-
-    // use attribute custom name or append the generic type names
-    // turns "PagedViewModel<RelationItemViewModel>" into "PagedRelationItem"
-    return $"{name}{string.Join(string.Empty, type.GenericTypeArguments.Select(SanitizedTypeName))}";
-}
-```
+**Solution**: `UmbracoSchemaIdGenerator.Generate()` flattens generic types:
+- `PagedViewModel<RelationItemViewModel>` becomes `PagedRelationItemModel`
 
 ---
 
 ## 7. Extending This Library
 
-### Adding a Custom OpenAPI Handler
-
-1. **Implement interface**:
-   ```csharp
-   public class MySchemaIdHandler : SchemaIdHandler
-   {
-       public override bool CanHandle(Type type)
-           => type.Namespace?.StartsWith("MyProject") is true;
+### Adding Custom OpenAPI Transformers
 
-       public override string Handle(Type type)
-           => $"My{base.Handle(type)}";
-   }
-   ```
+OpenAPI transformers are scoped per-document. To customize a document, implement `IOpenApiDocumentTransformer`, `IOpenApiOperationTransformer`, or `IOpenApiSchemaTransformer` and register with your OpenAPI options.
 
-2. **Register in consuming API**:
-   ```csharp
-   builder.Services.AddSingleton<ISchemaIdHandler, MySchemaIdHandler>();
-   ```
-
-**Note**: Handlers registered later take precedence in the selector.
+For schema ID generation, use the static `UmbracoSchemaIdGenerator.Generate(Type)` method.
 
 ### Customizing Problem Details
 
@@ -269,13 +240,9 @@ return BadRequest(problemDetails);
 
 ## 8. Project-Specific Notes
 
-### Why Virtual Handlers?
-
-**Decision**: Make `SchemaIdHandler`, `OperationIdHandler`, etc. virtual.
+### Per-Document Transformer Scoping
 
-**Why**: Management API and Delivery API have different schema ID requirements. Virtual methods allow override without rewriting the entire handler.
-
-**Example**: Management API might prefix all schemas with "Management", Delivery API with "Delivery".
+With Microsoft.AspNetCore.OpenApi, transformers are configured per OpenAPI document. This means custom transformers only apply to the documents they're registered with, not globally. Each API (Management, Delivery) configures its own transformers via `ConfigureUmbracoOpenApiOptionsBase` subclasses.
 
 ### Performance: Subtype Caching
 
@@ -304,9 +271,13 @@ return BadRequest(problemDetails);
 - Version: See `Directory.Packages.props`
 - Uses ASP.NET Core Data Protection for token encryption
 
-**Swashbuckle**:
-- OpenAPI 3.0 document generation
-- Custom filters: `EnumSchemaFilter`, `MimeTypeDocumentFilter`, `RemoveSecuritySchemesDocumentFilter`
+**Microsoft.AspNetCore.OpenApi**:
+- OpenAPI 3.1.1 document generation
+- Custom transformers: `SchemaIdTransformer`, `OperationIdTransformer`, `MimeTypeDocumentTransformer`, `ServerTransformer`
+
+**Swashbuckle.AspNetCore.SwaggerUI**:
+- Swagger UI for browsing and testing API endpoints
+- Accessed at `/umbraco/openapi/`
 
 **Asp.Versioning**:
 - API versioning via `ApiVersion` attribute
@@ -318,7 +289,7 @@ return BadRequest(problemDetails);
 
 ### Usage Pattern
 
-Consuming APIs call `builder.AddUmbracoApiOpenApiUI().AddUmbracoOpenIddict()`
+Consuming APIs call `builder.AddUmbracoOpenApi().AddUmbracoOpenIddict()`
 
 ---
 
@@ -346,7 +317,8 @@ dotnet list src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj package --v
 | Class | Purpose | File |
 |-------|---------|------|
 | `ProblemDetailsBuilder` | Build RFC 7807 error responses | Builders/ProblemDetailsBuilder.cs |
-| `SchemaIdHandler` | Generate OpenAPI schema IDs | OpenApi/SchemaIdHandler.cs |
+| `UmbracoSchemaIdGenerator` | Generate OpenAPI schema IDs | OpenApi/UmbracoSchemaIdGenerator.cs |
+| `UmbracoOperationIdTransformer` | Generate operation IDs | OpenApi/UmbracoOperationIdTransformer.cs |
 | `UmbracoJsonTypeInfoResolver` | Polymorphic JSON serialization | Serialization/UmbracoJsonTypeInfoResolver.cs |
 | `UmbracoBuilderAuthExtensions` | Configure OpenIddict | DependencyInjection/UmbracoBuilderAuthExtensions.cs |
 | `HideBackOfficeTokensHandler` | Secure cookie-based token storage | DependencyInjection/HideBackOfficeTokensHandler.cs |

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);
+    }
+}