Customize OpenAPI: add example for AllowAnonymous endpoints

[wadepickett]

Description

This issue was kindly identified by @Mohammed-Atef2004 who is also addressing the issue in a PR.
Also see the related upstream product repo issue: dotnet/aspnetcore#61264 - [OpenAPI] Cannot skip SecurityScheme for controllers with [AllowAnonymous]

Sumary

The current Customize OpenAPI documents documentation shows how to apply a Bearer security scheme to all endpoints using an IOpenApiDocumentTransformer, but does not demonstrate how to skip endpoints decorated with [AllowAnonymous].

This is a common real-world scenario. Developers using authentication typically have a mix of protected and anonymous endpoints and need security requirements applied conditionally.

Problem

The existing BearerSecuritySchemeTransformer example in the docs iterates over all operations and unconditionally adds a security requirement. There is no guidance on how to:

• Detect whether an endpoint has the [AllowAnonymous] attribute applied.
• Conditionally skip adding the security requirement for those endpoints.

Users have resorted to hacky workarounds (for example, using tags to mark anonymous endpoints) because the docs don't cover this pattern.

Proposed Documentation Change

Add a new subsection under Use operation transformers in aspnetcore/fundamentals/openapi/customize-openapi.md titled "Conditionally applying security requirements" that includes:

1. An explanation of when to use an IOpenApiOperationTransformer (instead of a document transformer) for per-operation conditional logic based on endpoint metadata.
2. A complete code example of an AuthOperationTransformer that:
   • Checks context.Description.ActionDescriptor.EndpointMetadata for AllowAnonymousAttribute.
   • Skips adding the security requirement if the attribute is present.
   • Adds a Bearer security requirement otherwise.
3. A note clarifying this transformer adds security requirements per operation and assumes the security scheme is already registered at the document level (cross-referencing the existing BearerSecuritySchemeTransformer example).

File(s) to Update

• aspnetcore/fundamentals/openapi/customize-openapi.md

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/customize-openapi.md

Document ID

ea5fce3c-e38f-9531-b77a-3e9a5e8e30ce

Platform Id

126b754a-260a-3efc-a261-b0d72ad0d8ce

Article author

@wadepickett

Metadata

• ID: ea5fce3c-e38f-9531-b77a-3e9a5e8e30ce
• PlatformId: 126b754a-260a-3efc-a261-b0d72ad0d8ce
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

---

Associated WorkItem - 563011

[wadepickett]

fixed with PR #36902