How to modify get-only schema properties for in OpenApi transformers

[jhavlicek-profinit]

Description

Many properties of OpenApi.NET objects provided to the transformers are interfaces that have get-only properties. It's not clear from documentation, how should the transformer be written to modify a get-only property. It does work with casting, but that seems like rather unclean solution.

Example: I want to set an Example property of a parameters

public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
{
    foreach (var parameter in operation.Parameters ?? [])
    {
        if (parameter.Name == "sort")
        {
            // parameter is a IOpenApiParameter. The Example property is get-only and can't be set. To set it, I cast it to a concrete type that has a setter.
            // The IOpenApiParameterinterface can be
            // * OpenApiParameter (further subclassed to OpenApiBodyParameter / OpenApiFormDataParameter) 
            // * or OpenApiParameterReference
            ((OpenApiParameter)parameter).Example = "something";
        }
    }

    return Task.CompletedTask;
}

Page URL

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

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

[wadepickett]

Thanks @jhavlicek-profinit for pointing this out. We could do better. Greatly appreciate that you took the time to let us know what is needed here.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-02-11
Issue: 36762
Model: GitHub Copilot

---

Issue Analysis: Clarify how to modify get-only interface properties in OpenAPI transformers

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The documentation for OpenAPI transformers in ASP.NET Core does not explain how to modify properties that are exposed as get-only through OpenAPI.NET interfaces (e.g., IOpenApiParameter). When writing operation transformers, developers receive objects typed as interfaces where key properties like Example are read-only. The only way to set these properties is by casting to the concrete implementation type (e.g., OpenApiParameter), but this pattern is not documented, leaving developers uncertain whether it is the recommended approach or a fragile workaround. This is a documentation gap affecting developers who need to customize OpenAPI output beyond the scenarios currently covered in the docs.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/openapi/customize-openapi.md	88-107	"Use operation transformers"
Code sample (10.x)	aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs	147-180	snippet_operationtransformer1
Include file (9.x)	aspnetcore/fundamentals/openapi/includes/customize-openapi9.md	76-91	"Use operation transformers"

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential Documentation Updates

File: aspnetcore/fundamentals/openapi/customize-openapi.md
Location: Lines 88-107 (within or after the "Use operation transformers" section)
Type: New note block + code example

Current content (lines 88-103):

## Use operation transformers

Operations are unique combinations of HTTP paths and methods in an OpenAPI document. Operation transformers are helpful when a modification:

* Should be made to each endpoint in an app, or
* Conditionally applied to certain routes.

Operation transformers have access to a context object which contains:

* The name of the document the operation belongs to.
* The <xref:Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription> associated with the operation.
* The <xref:System.IServiceProvider> used in document generation.

For example, the following operation transformer adds `500` as a response status code supported by all operations in the document.

[!code-csharp[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs?name=snippet_operationtransformer1)]

Suggested direction:

Add a [!NOTE] block and a code example after the existing operation transformer examples (after line 107) explaining how to work with interface-typed objects that have get-only properties. The note should cover:

1. That OpenAPI.NET exposes many objects via interfaces (e.g., IOpenApiParameter, IOpenApiSchema) where properties are get-only.
2. That to modify these properties, developers should use pattern matching to safely cast to the concrete type (e.g., OpenApiParameter) which exposes setters.
3. That developers should always check the type before casting, since different concrete types may be encountered (e.g., OpenApiParameter vs. OpenApiParameterReference).

> [!NOTE]
> Many OpenAPI.NET objects provided to transformers are exposed through interfaces with get-only properties (for example, `IOpenApiParameter`). To modify these properties, cast the interface to its concrete implementation type, which exposes settable properties. Always use pattern matching to safely check the type before casting.

The following example demonstrates how to set the `Example` property on an operation parameter by casting from the `IOpenApiParameter` interface to the `OpenApiParameter` concrete type:

```csharp
options.AddOperationTransformer((operation, context, cancellationToken) =>
{
    foreach (var parameter in operation.Parameters ?? [])
    {
        if (parameter.Name == "sort" && parameter is OpenApiParameter concreteParam)
        {
            concreteParam.Example = new JsonValue("name_asc");
        }
    }
    return Task.CompletedTask;
});

### Potential Code Sample Updates
**File:** [`aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/b5bc4cc60934d03a14e9a4a37b6059f274dcd892/aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs)
**Change:** Add a new snippet demonstrating safe casting from an interface to a concrete type within an operation transformer.

**Suggested direction:**
```csharp
#if OPERATIONtransformer_castexample
// <snippet_operationtransformer_cast>
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddOperationTransformer((operation, context, cancellationToken) =>
    {
        foreach (var parameter in operation.Parameters ?? [])
        {
            // IOpenApiParameter exposes get-only properties.
            // Cast to the concrete OpenApiParameter type to set values.
            if (parameter.Name == "sort" && parameter is OpenApiParameter concreteParam)
            {
                concreteParam.Example = new JsonValue("name_asc");
            }
        }
        return Task.CompletedTask;
    });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapGet("/items", (string? sort) => $"Sorted by {sort}");

app.Run();
// </snippet_operationtransformer_cast>
#endif

🎯 Suggested Action Plan

For documentation team review

1. Review file: aspnetcore/fundamentals/openapi/customize-openapi.md

   • Navigate to: Lines 88-107
   • Section: "Use operation transformers"
   • Consider: Add a [!NOTE] block explaining that transformer objects are interface-typed with get-only properties and that safe casting to concrete types is the recommended pattern for mutation.

2. Add code sample: aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs

   • Add a new snippet demonstrating safe pattern-matching cast from IOpenApiParameter to OpenApiParameter to set a get-only property.

3. Consider similar update for 9.x include: aspnetcore/fundamentals/openapi/includes/customize-openapi9.md

   • Section: "Use operation transformers"
   • Same note pattern may apply for the .NET 9 moniker.

⚠️ Review Considerations

• Verify that the casting pattern applies consistently across .NET 9 and .NET 10 versions of the OpenAPI.NET library used by ASP.NET Core.
• Confirm with OpenAPI.NET team whether casting to concrete types is the officially supported/recommended approach or if helper APIs are planned.
• Check if similar guidance is needed for schema transformers and document transformers (e.g., IOpenApiSchema, IOpenApiSecurityScheme), as the same interface pattern may apply.
• Consider whether this note should also appear in the schema transformers and document transformers sections for completeness.

🔗 References

• Published article: Customize OpenAPI documents
• Source file: customize-openapi.md
• OpenAPI.NET source: OpenApiParameter.cs on GitHub
• Issue: #36762