Update Open API document generation documentation to use Microsoft.AspNetCore.OpenApi (CMS 18.0)

18/umbraco-cms/.gitbook.yaml

@@ -160,3 +160,5 @@ redirects:
     customizing/extending-overview/foundation/repositories/repository-types/tree-repository.md: customizing/extending-overview/extension-types/tree/tree-repository.md
     customizing/extending-overview/extension-types/collections/collection-view.md: customizing/extending-overview/extension-types/collections/collection-view/README.md
     ai/developer-mcp/host-setup: ai/local-mcp-setup/README.md
+    reference/custom-swagger-api: reference/custom-backoffice-api.md
+    tutorials/creating-a-backoffice-api/adding-a-custom-swagger-document: tutorials/creating-a-backoffice-api/adding-a-custom-openapi-document.md

18/umbraco-cms/SUMMARY.md

@@ -393,7 +393,6 @@
   * [Custom Delivery API endpoints](reference/content-delivery-api/custom-delivery-api-endpoints.md)
 * [Webhooks](reference/webhooks/README.md)
   * [Expanding Webhook Events](reference/webhooks/expanding-webhook-events.md)
-* [API versioning and OpenAPI](reference/api-versioning-and-openapi.md)
 * [Searching](reference/searching/README.md)
   * [Examine](reference/searching/examine/README.md)
     * [Examine Management](reference/searching/examine/examine-management.md)
@@ -463,7 +462,8 @@
 * [Management API](reference/management-api/README.md)
   * [External Access](reference/management-api/external-access.md)
   * [Setup OAuth using Postman](reference/management-api/postman-setup-swagger.md)
-* [Custom Swagger API](reference/custom-swagger-api.md)
+* [Custom Backoffice API](reference/custom-backoffice-api.md)
+* [API versioning and OpenAPI](reference/api-versioning-and-openapi.md)
 * [Umbraco Flavored Markdown](reference/umbraco-flavored-markdown.md)
 * [Content Type Filters](reference/content-type-filters.md)
 * [Database Availability Checks](reference/database-availability.md)
@@ -550,7 +550,7 @@
 * [Create a custom maintenance page](tutorials/create-a-custom-maintenance-page.md)
 * [Creating a backoffice API](tutorials/creating-a-backoffice-api/README.md)
   * [Documenting your controllers](tutorials/creating-a-backoffice-api/documenting-your-controllers.md)
-  * [Adding a custom Swagger document](tutorials/creating-a-backoffice-api/adding-a-custom-swagger-document.md)
+  * [Adding a custom OpenAPI document](tutorials/creating-a-backoffice-api/adding-a-custom-openapi-document.md)
   * [Versioning your API](tutorials/creating-a-backoffice-api/versioning-your-api.md)
   * [Polymorphic output in the Management API](tutorials/creating-a-backoffice-api/polymorphic-output-in-the-management-api.md)
   * [Umbraco schema and operation IDs](tutorials/creating-a-backoffice-api/umbraco-schema-and-operation-ids.md)

18/umbraco-cms/customizing/development-flow/umbraco-extension-template.md

@@ -38,7 +38,7 @@ This command creates a new folder called `MyExtension` with the following files
 
 The `-ex` flag indicates that you want to include examples of how to use the extension. This flag is optional, but it is recommended to include it if you are new to building extensions for Umbraco. It will additionally give you:
 
-- `Composers`: A folder containing an example composer that registers a custom Swagger API.
+- `Composers`: A folder containing an example composer that registers a custom OpenAPI document for the API.
 - `Controllers`: A folder containing an example API controller for a dashboard.
 - `Client/src/api`: A folder containing an example API client that calls the API controller.
 - `Client/src/dashboards`: A folder containing an example dashboard Web Component that uses the API client.

18/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md

@@ -21,7 +21,122 @@ Use the [general upgrade guide](../) to complete the upgrade of your project.
 
 <summary>Umbraco 18</summary>
 
-*Add details about breaking changes in Umbraco 18 here.*
+**Swashbuckle replaced with Microsoft.AspNetCore.OpenApi**
+
+Umbraco no longer uses Swashbuckle for OpenAPI documentation. It has been replaced with [Microsoft.AspNetCore.OpenApi](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview).
+
+If you have custom APIs with OpenAPI documentation, you will need to update your code.
+
+*Registering OpenAPI documents*
+
+Replace `IConfigureOptions<SwaggerGenOptions>` with `AddOpenApi()`. This can be done in `Program.cs` or in a composer. See [Adding your own OpenAPI documents](../../../../reference/api-versioning-and-openapi.md#adding-your-own-openapi-documents) for details.
+
+Before:
+
+```csharp
+public class MyApiConfigureSwaggerGenOptions : IConfigureOptions<SwaggerGenOptions>
+{
+    public void Configure(SwaggerGenOptions options)
+    {
+        options.SwaggerDoc("my-api-v1", new OpenApiInfo { Title = "My API v1", Version = "1.0" });
+    }
+}
+
+// In a composer:
+builder.Services.ConfigureOptions<MyApiConfigureSwaggerGenOptions>();
+```
+
+After:
+
+```csharp
+// In Program.cs or a composer:
+builder.Services.AddOpenApi("my-api-v1", options =>
+{
+    options.AddDocumentTransformer((document, context, cancellationToken) =>
+    {
+        document.Info.Title = "My API v1";
+        document.Info.Version = "1.0";
+        return Task.CompletedTask;
+    });
+});
+
+// Add the document to the Swagger UI dropdown
+builder.Services.AddOpenApiDocumentToUi("my-api-v1", "My API v1");
+```
+
+Note that `AddOpenApiDocumentToUi()` is required to show the document in Swagger UI. Previously with Swashbuckle, documents were automatically added to the UI when registered. The second parameter (title) is optional and defaults to the document name if not specified.
+
+*Backoffice security requirements*
+
+Replace `BackOfficeSecurityRequirementsOperationFilterBase` with the `AddBackofficeSecurityRequirements()` extension method. See [Custom Backoffice API](../../../../reference/custom-backoffice-api.md) for a complete example.
+
+Before:
+
+```csharp
+public class MyApiSecurityRequirementsOperationFilter : BackOfficeSecurityRequirementsOperationFilterBase
+{
+    protected override string ApiName => "my-api-v1";
+}
+
+options.OperationFilter<MyApiSecurityRequirementsOperationFilter>();
+```
+
+After:
+
+```csharp
+builder.Services.AddOpenApi("my-api-v1", options =>
+{
+    options.AddBackofficeSecurityRequirements();
+});
+```
+
+*Schema ID handlers*
+
+The `ISchemaIdHandler` interface and `SchemaIdHandler` base class have been removed. Use `CreateSchemaReferenceId` on `OpenApiOptions` instead. See [Adding custom schema IDs](../../../../reference/api-versioning-and-openapi.md#adding-custom-schema-ids) for details.
+
+*Operation ID handlers*
+
+The `IOperationIdHandler` interface and `OperationIdHandler` base class have been removed. Use `IOpenApiOperationTransformer` instead. See [Adding custom operation IDs](../../../../reference/api-versioning-and-openapi.md#adding-custom-operation-ids) for details.
+
+*Delivery API member authentication*
+
+The class `ConfigureUmbracoMemberAuthenticationDeliveryApiSwaggerGenOptions` has been removed. Use the `AddDeliveryApiOpenApiMemberAuthentication()` extension method to add member authentication support to the Delivery API OpenAPI document:
+
+```csharp
+using Umbraco.Cms.Api.Delivery.OpenApi;
+
+builder.Services.AddDeliveryApiOpenApiMemberAuthentication();
+```
+
+For more details, see [Testing with Swagger](../../../../reference/content-delivery-api/protected-content-in-the-delivery-api/README.md#testing-with-swagger).
+
+*OpenAPI route and availability configuration*
+
+If you were previously overriding the `OpenApiRouteTemplatePipelineFilter` methods (`OpenApiIsEnabled`, `OpenApiRouteTemplate`, or `OpenApiUiRoutePrefix`) to customize OpenAPI routes or availability, you should migrate to using `UmbracoOpenApiOptions` instead. The pipeline filter methods are now private implementation details.
+
+Use `PostConfigure` to override the defaults:
+
+```csharp
+builder.Services.PostConfigure<UmbracoOpenApiOptions>(options =>
+{
+    options.Enabled = true;
+    options.RouteTemplate = "openapi/{documentName}.json";
+    options.UiRoutePrefix = "openapi";
+});
+```
+
+See [OpenAPI route and/or availability](../../../../reference/api-versioning-and-openapi.md#openapi-route-andor-availability) for details.
+
+*OpenAPI URL changes*
+
+The OpenAPI endpoints have been renamed from "swagger" to "openapi" to follow Microsoft's naming conventions:
+
+| Old URL | New URL |
+|---------|---------|
+| `/umbraco/swagger` | `/umbraco/openapi` |
+| `/umbraco/swagger/{documentName}/swagger.json` | `/umbraco/openapi/{documentName}.json` |
+
+For more details, see the [API versioning and OpenAPI](../../../../reference/api-versioning-and-openapi.md) article.
 
 </details>
 
@@ -453,7 +568,7 @@ This configuration will no longer have an effect.
 
 Notifications have changed their behavior to an extent. You can still implement notifications such as `ContentSavingNotification` to react to changes for related systems or add messages to be shown in the Backoffice. You can no longer modify the models being transferred through the API.
 
-If you wish to modify the Backoffice UI, register the extensions through the manifest system that hook on to the desired areas of the Backoffice UI. If you used to modify the models because you needed more data on the models, it's recommended that you build your own API controller to achieve this. You can read more about [building custom API controllers on the Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/reference/custom-swagger-api) and even learn how to register your controllers in the Swagger UI.
+If you wish to modify the Backoffice UI, register the extensions through the manifest system that hook on to the desired areas of the Backoffice UI. If you used to modify the models because you needed more data on the models, it's recommended that you build your own API controller to achieve this. You can read more about [building custom API controllers on the Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/reference/custom-backoffice-api) and even learn how to register your controllers in Swagger UI.
 
 * **Property editors have been split in two**