dotnet/aspnet-api-versioning v10.0.0-preview.2

10.0.0 Preview 2

on GitHub

This release is a quick iteration which contains minor fixes based on feedback from Preview 1.

Trying out previews is always a big ask. The OpenAPI extensions are net new, so I really am looking for some community support to flush out any edge cases I may have been missed before releasing officially. All other libraries are stable.

Aside from whatever the community may report, there are only two final things I'm considering for the final release:

1. gRPC versioning support, which I'm waiting on grpc/grpc-dotnet#2690 and grpc/grpc-dotnet#2693
2. Coordination with Microsoft to open up types in Microsoft.AspNetCore.OpenAPI so I don't have to resort to Reflection for integration

If these are not able to be completed within the next few weeks, then I will officially release the stable libraries. The gRPC support will then come in a future, likely minor version, release. The OpenAPI extensions may stay in preview as AOT will likely be broken.

Features

All Platforms

• Support _ prefix character when extracting API versions from a .NET namespace (#1172)
• Generate software bill of materials (SBOM) (#1100)

Fixes

ASP.NET Core with OpenAPI

• Build-time OpenAPI documents have empty paths (#1165, #1168)
• Missing XML Comments (#1169)
• Support <example> tags (#1170)

Breaking Changes

The OpenAPI extensions for API Versioning (e.g. x-api-versioning) will now use a nested links property rather than a simple array. This allows the schema to be open for possible future enhancements.

Preview 1

{
    "x-api-versioning":
    [
        {
            "title": "Version Policy",
            "type": "text/html",
            "rel": "info",
            "url": "http://my.api.com/policies/versioning.html"
        }
    ]
}

Preview 2+

{
    "x-api-versioning":
    {
        "links":
        [
            {
                "title": "Version Policy",
                "type": "text/html",
                "rel": "info",
                "url": "http://my.api.com/policies/versioning.html"
            }
        ]
    }
}

Contributors

• Thanks to @sander1095 for reporting and fixing the OpenAPI document generation in Minimal APIs (#1165)
• Thanks to @xavierjohn for adding enhanced support to allow namespaces that start with _ (#1172)