chore: upgrade Asp.Versioning.Mvc to v10.0.0

Open
  • Is something wrong?
#165 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Quiet
Tech stack
csharp, openapi
Domain
backend-api-design

Research direction

First check whether Asp.Versioning.OpenApi has reached a stable NuGet release; the issue says to wait until it has. Then review TaskFlow.Api.csproj, Extensions/ApiVersioningServiceExtensions.cs, Extensions/OpenApiServiceExtensions.cs, and Program.cs for the versioning and OpenAPI wiring. Verify the Scalar UI, version tagged OpenAPI output, test suite, and vulnerable package report against the acceptance criteria.

Written by the indexing model from the issue text.

Description

blocked

On hold (2026-10-30), part of #372 (Move to .NET 11). Verified from the NuGet nuspecs: Asp.Versioning.OpenApi 10.2.3 depends on Microsoft.OpenApi [2.7.5, 3.0.0) and on Microsoft.AspNetCore.OpenApi 10.0.10, and Asp.Versioning.Mvc 10.2.1 targets net10.0 only. The 2.7.5 pin in this repo satisfies that range, so the migration itself should resolve cleanly on .NET 10. But the <3.0.0 cap is exactly what #301 has to get past: Microsoft.AspNetCore.OpenApi 11.x needs Microsoft.OpenApi 3.10.2 or later. Adopting Asp.Versioning.OpenApi now would block the .NET 11 move until Asp.Versioning ships a release that accepts Microsoft.OpenApi 3.x. 8.1.1 works on .NET 10, so there is no urgency. Take this with the .NET 11 move, or when such a release exists, whichever is first.

Background

Asp.Versioning.Mvc and Asp.Versioning.Mvc.ApiExplorer were held at 8.1.1 in #164 (backend NuGet dependency audit). The 10.x line carries breaking changes to OpenAPI wiring that require a dedicated migration.

Update (2026-10-12): the prerequisite is met. Asp.Versioning.OpenApi now has stable releases, and the latest versions on NuGet are:

Package Currently pinned Latest stable
Asp.Versioning.Mvc 8.1.1 10.2.1
Asp.Versioning.Mvc.ApiExplorer 8.1.1 10.2.1
Asp.Versioning.OpenApi (new) not referenced 10.2.3

The original target of 10.0.0 is superseded. Target the latest stable release, and review the changelogs between 10.0.0 and 10.2.x for further breaking changes.

What needs to change

Version 10 changes how OpenAPI integration is wired:

  • The old pattern (services.AddOpenApi("v1", options => ...) from Microsoft.AspNetCore) is replaced by a fluent chain: AddApiVersioning().AddApiExplorer().AddOpenApi()
  • app.MapOpenApi() must be replaced by app.MapOpenApi().WithDocumentPerVersion()
  • The custom ApiVersionDocumentTransformer in Extensions/OpenApiServiceExtensions.cs may need to be adapted or replaced by the new VersionedOpenApiOptions surface
  • A new companion package Asp.Versioning.OpenApi is required

Things to watch

  • Microsoft.OpenApi is pinned to 2.7.5 to resolve CVE-2026-49451 (commit 0c60491). Confirm Asp.Versioning.OpenApi resolves cleanly with that pin and that the CVE stays fixed (dotnet list package --vulnerable).
  • Current wiring: Program.cs calls AddApiVersioningConfiguration() and OpenApiServiceExtensions.AddOpenApi(...), and app.UseOpenApiWithScalar().

Files likely affected

  • TaskFlow.Api/TaskFlow.Api.csproj — add Asp.Versioning.OpenApi, bump Asp.Versioning.Mvc and Asp.Versioning.Mvc.ApiExplorer to the latest stable (10.2.1)
  • TaskFlow.Api/Extensions/ApiVersioningServiceExtensions.cs
  • TaskFlow.Api/Extensions/OpenApiServiceExtensions.cs
  • TaskFlow.Api/Program.cs (if MapOpenApi call needs updating)

Acceptance criteria

  • Asp.Versioning.OpenApi is at a stable release (10.2.3 as of 2026-10-12)
  • Asp.Versioning.Mvc and Asp.Versioning.Mvc.ApiExplorer updated to the latest stable (10.2.1)
  • Scalar UI at /scalar/v1 renders correctly with API version selection working
  • Generated OpenAPI JSON is valid and version-tagged
  • npm run gen:api still produces a working client (the generator reads the live OpenAPI spec)
  • All backend tests pass (dotnet test) and dotnet format --verify-no-changes is clean
  • dotnet list package --vulnerable reports zero findings
Dominant language
C#
Stars
1
Forks
0
Avg merge
2h 2m
Merged PRs (30d)
98

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nevridge/TaskFlow

All issues in nevridge/TaskFlow

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.