Update Open API document generation documentation to use `Microsoft.AspNetCore.OpenApi` (CMS 18.0) by lauraneto · Pull Request #8021 · umbraco/UmbracoDocs

lauraneto · 2026-04-29T12:35:28Z

📋 Description

Added documentation relating to the switch from using the Swashbuckle package to using the Microsoft one for Open API document generation, done in umbraco/Umbraco-CMS#21058.

This contribution was AI assisted.

📎 Related Issues (if applicable)

umbraco/Umbraco-CMS#21058
umbraco/Umbraco-CMS#22774

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

Code blocks are correctly formatted.
Sentences are short and clear (preferably under 25 words).
Passive voice and first-person language (“we”, “I”) are avoided.
Relevant pages are linked.
All links work and point to the correct resources.
Screenshots or diagrams are included if useful.
Any code examples or instructions have been tested.
Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

CMS 18.0

Deadline (if relevant)

To be published along with the beta release if possible, on Wednesday 13th May.

- Rename custom-swagger-api to custom-backoffice-api with redirect - Rename adding-a-custom-swagger-document to adding-a-custom-openapi-document - Update patterns from Swashbuckle to Microsoft.AspNetCore.OpenApi: - Use AddOpenApi() instead of IConfigureOptions<SwaggerGenOptions> - Use UmbracoSchemaIdGenerator instead of ISchemaIdHandler - Use UmbracoOperationIdTransformer instead of IOperationIdHandler - Use AddBackofficeSecurityRequirements() extension method - Update ConfigureUmbracoMemberAuthenticationDeliveryApiSwaggerGenOptions to ConfigureUmbracoMemberAuthenticationDeliveryApiOpenApiOptions - Update terminology from "Swagger document" to "OpenAPI document" - Reorganize api-versioning-and-openapi.md for better structure - Fix absolute URL to relative in content-delivery-api

Document breaking changes for the switch from Swashbuckle to Microsoft.AspNetCore.OpenApi including: - Registering OpenAPI documents with AddOpenApi() - Backoffice security requirements - Schema ID handlers replacement - Operation ID handlers replacement - Delivery API member authentication class rename

- Replace MapToApi attribute with ShouldInclude namespace filtering - Add SwaggerUIOptions configuration for Swagger UI dropdown - Fix custom operation ID transformer (remove unnecessary namespace check, fix namespace) - Add hints explaining CreateSchemaReferenceId behavior and UmbracoSchemaIdGenerator - Fix OpenApiRouteTemplatePipelineFilter method signatures (IServiceProvider) - Update multiple API versions example with ShouldInclude filtering

- Update api-versioning-and-openapi.md to use UmbracoOpenApiOptions - Clarify that disabling OpenAPI in production is for public-facing websites - Add v18 upgrade notes for migrating to UmbracoOpenApiOptions

- Update all /umbraco/swagger URLs to /umbraco/openapi - Clarify that OpenAPI docs use Microsoft.AspNetCore.OpenApi and UI uses Swashbuckle.AspNetCore.SwaggerUI - Add "Using an alternative OpenAPI UI" section with DefaultUiEnabled option - Update upgrade notes for v18 URL changes - Keep OAuth client ID references as umbraco-swagger (unchanged for compatibility) Co-Authored-By: Claude <noreply@anthropic.com>

- Replace Configure<SwaggerUIOptions> with AddOpenApiDocumentToUi() in all examples - Update upgrade notes to mention that AddOpenApiDocumentToUi is required (unlike Swashbuckle where documents were automatically added to the UI) - Update import statements from Swashbuckle.AspNetCore.SwaggerUI to Umbraco.Cms.Api.Common.DependencyInjection

…ethod Replace references to the removed ConfigureUmbracoMemberAuthenticationDeliveryApiOpenApiOptions class with the new simpler AddDeliveryApiOpenApiMemberAuthentication() extension method.

# Conflicts: # 17/umbraco-cms/.gitbook.yaml # 17/umbraco-cms/SUMMARY.md # 17/umbraco-cms/tutorials/creating-a-backoffice-api/documenting-your-controllers.md

The OpenAPI migration docs were originally added to the 17/ folder because the 18/ folder didn't exist yet. Moves all changes to 18/ and reverts 17/ to match main.

github-actions · 2026-04-29T12:36:36Z

 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.


⚠️ [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

github-actions · 2026-04-29T12:36:36Z

 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.


⚠️ [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

github-actions · 2026-04-29T12:36:36Z

 ![Umbraco Management API Authorize Login](../../.gitbook/assets/management-api-swagger-authorize-instructions.png)

-The available integration for the authorization is done via a backoffice user with the integration of `OAuth2, authorizationCode with PKCE`. Swagger is only enabled in non-production environments, so if you need to access the Management API in production, you need a different client.
+The available integration for the authorization is done via a backoffice user with the integration of `OAuth2, authorizationCode with PKCE`. The OpenAPI UI is only enabled in non-production environments, so if you need to access the Management API in production, you need a different client.


⚠️ [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

github-actions · 2026-04-29T12:36:36Z

+Swagger UI sometimes has persistent caching, which can prevent the new definition from appearing immediately. If this happens, disable caching in the **Network** tab of your browser's developer tools.
+{% endhint %}
+
+{% hint style="info" %}


⚠️ [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

AndyButland

Looks good from my perspective @lauraneto. From a read through I just had a few suggestions/questions:

Worth documenting the new OnPreMapEndpoints and OnPostMapEndpoints on IUmbracoPipelineFilter? Not sure if there's an existing page for this that needs an update, or if it would be something new.

I'm a bit confused by MapToApi and ShouldInclude - the latter of which is discussed here. I.e. are both valid, both needed, or can either be used to map an API endpoint to a document?

Worth discussing removed types and replacements in the breaking changes section? E.g. MimeTypeDocumentFilter to MimeTypesTransformer.

Although it's the opposite of a breaking change, maybe worth mentioning that the OAuth client ID for the OpenAPI UI remains umbraco-swagger for backwards compatibility with existing database registrations in umbracoOpenIddictApplications (just in case there's any confusion why that hasn't changed).

# Conflicts: # 18/umbraco-cms/SUMMARY.md

- custom-generated-client.md: update example URL, replace removed BackOfficeSecurityRequirementsOperationFilterBase with AddBackofficeSecurityRequirements() on OpenApiOptions - api-versioning-and-openapi.md, management-api/README.md: drop Swashbuckle package reference, just call the UI Swagger UI - postman-setup-swagger.md: default download is management.json

…s hooks

In v17 Swashbuckle had a global filter that honored [MapToApi] across all documents. In v18 each document has its own ShouldInclude predicate, so the attribute is only honored automatically for Umbraco's built-in documents. Custom documents must check it inside ShouldInclude. Add a 'How filtering works' section to the API versioning reference and an upgrade note covering the v17 to v18 delta.

Reorganize the article so versioning topics group together, drop the "Customizing your OpenAPI document" / "Advanced configuration" wrappers, flatten the operation-IDs H4 nest, and lead with the three OpenAPI documents Umbraco ships. Update cross-references in the v18 upgrade notes and the schema/operation IDs tutorial to match the new anchors.

…asing

…llers

…koffice OpenAPI documents

sofietoft · 2026-05-11T17:47:08Z

Hej @lauraneto

Could you please let me know if this should be published a long with the beta release Wednesday, or if it can wait until the RC later in the month?

lauraneto · 2026-05-12T07:25:51Z

Hi @sofietoft,

This should be posted along with the beta indeed, as it relates to breaking changes.
Sorry for the short notice, but we were still ironing out some details.

# Conflicts: # 17/umbraco-cms/develop-with-umbraco/headless-and-apis/management-api/README.md # 17/umbraco-cms/extend-your-project/backoffice-extensions/development-flow/umbraco-extension-template.md # 17/umbraco-cms/extend-your-project/server-side-extensions/custom-backoffice-api.md # 17/umbraco-cms/extend-your-project/server-side-extensions/custom-swagger-api.md # 17/umbraco-cms/extend-your-project/tutorials/creating-a-backoffice-api/adding-a-custom-openapi-document.md # 17/umbraco-cms/extend-your-project/tutorials/creating-a-backoffice-api/adding-a-custom-swagger-document.md # 18/umbraco-cms/.gitbook.yaml # 18/umbraco-cms/SUMMARY.md # 18/umbraco-cms/get-started/upgrading-and-migrating/version-specific/migrating-macros.md

lauraneto and others added 10 commits December 19, 2025 18:06

Add documentation for ExcludeFromDefaultOpenApiDocument attribute

c61c752

Update OpenAPI documentation for UmbracoOpenApiOptions

9fea065

- Update api-versioning-and-openapi.md to use UmbracoOpenApiOptions - Clarify that disabling OpenAPI in production is for public-facing websites - Add v18 upgrade notes for migrating to UmbracoOpenApiOptions

Update docs for AddDeliveryApiOpenApiMemberAuthentication extension m…

3070883

…ethod Replace references to the removed ConfigureUmbracoMemberAuthenticationDeliveryApiOpenApiOptions class with the new simpler AddDeliveryApiOpenApiMemberAuthentication() extension method.

Merge branch 'main' into cms/v18/microsoft-open-api-docs

4a456c5

# Conflicts: # 17/umbraco-cms/.gitbook.yaml # 17/umbraco-cms/SUMMARY.md # 17/umbraco-cms/tutorials/creating-a-backoffice-api/documenting-your-controllers.md

Move OpenAPI documentation changes from v17 to v18

67d829e

The OpenAPI migration docs were originally added to the 17/ folder because the 18/ folder didn't exist yet. Moves all changes to 18/ and reverts 17/ to match main.

github-actions Bot reviewed Apr 29, 2026

View reviewed changes

lauraneto mentioned this pull request Apr 29, 2026

Open API: Use Microsoft.AspNetCore.OpenApi for Open API document generation umbraco/Umbraco-CMS#21058

Merged

7 tasks

Address vale linter feedback from PR review

a5e2a84

github-actions Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread 18/umbraco-cms/reference/custom-backoffice-api.md Outdated

AndyButland reviewed Apr 30, 2026

View reviewed changes

lauraneto added 4 commits May 7, 2026 10:47

Merge branch 'main' into cms/v18/microsoft-open-api-docs

97578c9

# Conflicts: # 18/umbraco-cms/SUMMARY.md

Document new IUmbracoPipelineFilter PreMapEndpoints / PostMapEndpoint…

34b59fc

…s hooks

github-actions Bot reviewed May 11, 2026

View reviewed changes

Comment thread 18/umbraco-cms/reference/api-versioning-and-openapi.md Outdated

Comment thread 18/umbraco-cms/reference/api-versioning-and-openapi.md Outdated

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

lauraneto added 10 commits May 11, 2026 10:23

Trim v18 OpenAPI upgrade notes to link out to reference docs

8168e00

Tidy custom-backoffice-api walkthrough wording

fb894ad

Slim adding-a-custom-openapi-document tutorial

b8ef878

Tighten umbraco-schema-and-operation-ids tutorial wording

c4ea685

Sharpen custom-generated-client AllowAnonymous behavior and heading c…

bf392c7

…asing

Remove migrating-macros tutorial

d9419cd

Tighten OpenAPI wording in management-api and documenting-your-contro…

04855b3

…llers

Fix schema ID example and use composer pattern for custom backoffice API

f3f59ab

Document AddBackOfficeOpenApiDocument as the recommended path for bac…

6ce8224

…koffice OpenAPI documents

Add more details to the OpenAPI upgrade notes

e43c6ba

lauraneto marked this pull request as ready for review May 11, 2026 17:58

lauraneto requested a review from AndyButland May 11, 2026 17:59

sofietoft and others added 4 commits May 12, 2026 09:38

Minor grammar

d6bdadd

Grammar fixes

701a067

Fix description punctuation in OpenAPI document tutorial

5d579d2

Revert v18 upgrade notes changes (already added in #8049)

ea0dbae

lauraneto added the category/umbraco-cms label May 12, 2026

lauraneto added 2 commits May 15, 2026 12:00

Restore links in v18 upgrade notes

6df2238

github-actions Bot reviewed May 15, 2026

View reviewed changes

Comment thread 18/umbraco-cms/get-started/upgrading-and-migrating/version-specific/README.md

Comment thread 18/umbraco-cms/get-started/upgrading-and-migrating/version-specific/README.md

sofietoft approved these changes May 18, 2026

View reviewed changes

sofietoft merged commit 5f98869 into main May 18, 2026
3 of 4 checks passed

sofietoft deleted the cms/v18/microsoft-open-api-docs branch June 15, 2026 07:40

Uh oh!

Conversation

lauraneto commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Description

📎 Related Issues (if applicable)

✅ Contributor Checklist

Product & Version (if relevant)

Deadline (if relevant)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AndyButland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sofietoft commented May 11, 2026

Uh oh!

lauraneto commented May 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lauraneto commented Apr 29, 2026 •

edited

Loading