Skip to main content

Migration Guides

v10.2.1 → v10.3.0​

No breaking changes​

This release is additive. Route groups can now be documented once instead of annotating every endpoint:

using RA.Utilities.OpenApi.Extensions;

var orders = app.MapGroup("/orders")
    .WithTags("Orders")
    .WithGroupSummary("Order management")
    .WithGroupDescription("Create, update, and track customer orders.");

GroupTagsDocumentTransformer writes the composed text into the OpenAPI tags the group's endpoints carry, and AddDefaultsDocumentTransformer() registers it automatically. If you register transformers individually, call options.AddGroupTagsDocumentTransformer(...).

No source changes are required. Existing output is unchanged for APIs that do not use WithGroupSummary() / WithGroupDescription().

Notes​

  • Group documentation is written only to tags the endpoints actually carry (via .WithTags(...)), and an existing tag description is never overwritten.
  • AddGroupTagsDocumentTransformer(IDictionary<string, string> tags) requires a tags argument but currently ignores it.

Known issue (unchanged)​

AddHealthChecksDocumentTransformer(IDictionary<string, string> tags) still registers HeadersParameterTransformer instead of HealthChecksDocumentTransformer, and the tags argument is ignored. Use AddDefaultsDocumentTransformer() until this is corrected.

v10.1.1 → v10.2.0​

No breaking changes​

This release is additive. ValueObjectSchemaTransformer documents the constraints of the value objects from RA.Utilities.Core.ValueObjects, and AddDefaultsDocumentTransformer() registers it automatically.

Existing OpenAPI output is unchanged except for the enriched component schemas and parameter schemas for Email, Currency, SSN, IBAN, and Money. If you register transformers individually, add the transformer explicitly:

builder.Services.AddOpenApi(options =>
{
    options.AddDefaultsDocumentTransformer(); // already includes the value object schemas
});

or:

builder.Services.AddOpenApi(options =>
{
    options.AddValueObjectSchemaTransformer();
});

The package now depends on RA.Utilities.Core.ValueObjects 10.2.0. No source changes are required.

Known issue (unchanged)​

AddHealthChecksDocumentTransformer(IDictionary<string, string> tags) still registers HeadersParameterTransformer instead of HealthChecksDocumentTransformer, and the tags argument is ignored. Use AddDefaultsDocumentTransformer() until this is corrected.

v10.1.0 → v10.1.1​

Breaking Change: DependencyInjectionExtensions renamed to OpenApiOptionsExtensions​

The static class holding the registration extension methods was renamed from DependencyInjectionExtensions to OpenApiOptionsExtensions, and the methods are now declared as C# 14 extension members on OpenApiOptions.

Extension-method call sites are unaffected — options.AddDefaultsDocumentTransformer(), options.AddFluentValidationRules(), options.AddTagOperationTransformer(...), and the rest keep working with the same names and signatures. Only code that references the class by name breaks:

// ❌ v10.1.0
Type extensions = typeof(DependencyInjectionExtensions);
DependencyInjectionExtensions.AddDefaultsDocumentTransformer(options);

// ✅ v10.1.1
Type extensions = typeof(OpenApiOptionsExtensions);
OpenApiOptionsExtensions.AddDefaultsDocumentTransformer(options);

Add using RA.Utilities.OpenApi.Extensions; as before — the namespace is unchanged.

Other Changes (non-breaking)​

  • DocumentInfoTransformer now populates Summary: OpenApiInfoSettings.Summary is applied to document.Info.Summary. Previously the Summary setting was ignored and the document summary stayed null.
  • Response models moved to a new namespace: this package now references RA.Utilities.Api.Response 10.1.0, which renames the response namespace from RA.Utilities.Api.Results to RA.Utilities.Api.Response. The OpenApi public API is unchanged; update using directives only if your custom transformers or examples reference those models directly. See the Api.Response migration guide.

Known issue (unchanged from v10.1.0)​

AddHealthChecksDocumentTransformer(IDictionary<string, string> tags) still registers HeadersParameterTransformer instead of HealthChecksDocumentTransformer, and the tags argument is ignored. Use AddDefaultsDocumentTransformer() until this is corrected.

v10.0.11 → v10.1.0​

No breaking changes​

This release is additive. AddDefaultsDocumentTransformer() now also registers HealthChecksDocumentTransformer, which documents the GET /health (JSON health report) and GET /alive (plain-text liveness) endpoints under the Health tag. Paths, schemas, and tags already present in the document are left untouched.

Known issue​

AddHealthChecksDocumentTransformer(IDictionary<string, string> tags) currently registers HeadersParameterTransformer instead of HealthChecksDocumentTransformer, and ignores tags. Prefer AddDefaultsDocumentTransformer() until this is corrected.

v10.0.10 → v10.0.11​

Breaking Change: OpenApiResponseExample.StatusCodes → StatusCode​

The property was renamed to reflect that it holds a single HTTP status code, not a collection.

// ❌ v10.0.10
example.StatusCodes = 200;

// ✅ v10.0.11
example.StatusCode = 200;

Other Changes (non-breaking)​

  • AddDefaultsDocumentTransformer now throws on null: Previously, passing null options silently skipped all transformers. Now throws ArgumentNullException.
  • DefaultResponsesOperationTransformer dedup fixed: The 500 response is no longer added multiple times to the same operation.
  • OpenApiOperationUtilities.AddResponseExample null-safe: No longer throws NullReferenceException when operation.Responses is null.
  • FluentValidationSchemaTransformer boolean format: ExclusiveMinimum/ExclusiveMaximum now produce lowercase "true"/"false" instead of culture-dependent "True"/"False".
  • EnumXmlSchemaTransformer performance: Fixed a bug where missing XML files caused the lock to be re-entered on every schema transformation call.
  • HeadersParameterSettings deterministic examples: Example GUID values are now fixed instead of randomized per instantiation.
  • Filename fixed: DepenenceInjectionExtensions.cs → DependencyInjectionExtensions.cs.

Verify the upgrade​

// If using OpenApiResponseExample, rename StatusCodes to StatusCode
example.StatusCode = 200;

// If using AddDefaultsDocumentTransformer, ensure options is not null
options.AddDefaultsDocumentTransformer(); // throws if options is null

v10.0.2 → v10.0.3​

Breaking Change: Transformers made internal​

The following transformers were made internal sealed to enforce consistent registration through extension methods:

  • BearerSecurityDocumentTransformer
  • DocumentInfoTransformer
  • HeadersParameterTransformer
  • PolymorphismDocumentTransformer
  • DefaultResponsesOperationTransformer

Before:

builder.Services.AddOpenApiDocumentTransformer<BearerSecurityDocumentTransformer>();

After:

builder.Services.AddOpenApi(options =>
    options.AddBearerSecurityDocumentTransformer());

Renames​

  • BearerSecuritySchemeTransformer → BearerSecurityDocumentTransformer
  • PolymorphismSchemaFilter → PolymorphismDocumentTransformer

Full Changelog​

See the package release notes for a complete version history.