Upgrade Swashbuckle.AspNetCore to v10.1.5 with Microsoft.OpenApi v2.x namespace fix

[Copilot]

Swashbuckle.AspNetCore v10 requires Microsoft.OpenApi v2.x, which moved OpenApiInfo (and related types) from Microsoft.OpenApi.Models to the root Microsoft.OpenApi namespace — causing CS0234 build failures with the old using directive.

Changes

• RESTRunner.Web.csproj: Upgraded Swashbuckle.AspNetCore and Swashbuckle.AspNetCore.Newtonsoft from v9.0.4 → v10.1.5; resolves Microsoft.OpenApi v2.4.1 transitively
• Program.cs: Updated namespace import to match OpenApi v2.x type location

// Before (v9 / Microsoft.OpenApi v1.x)
using Microsoft.OpenApi.Models;

// After (v10 / Microsoft.OpenApi v2.x)
using Microsoft.OpenApi;

All existing AddSwaggerGen configuration — TagActionsBy, DocInclusionPredicate, UseAllOfToExtendReferenceSchemas, UseSwaggerUI — is API-compatible with v10 and required no changes.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Upgrade Swashbuckle.AspNetCore to v10 with Microsoft.OpenApi v2.x compatibility</issue_title>
<issue_description>## Overview
Upgrade Swashbuckle.AspNetCore from v9.0.4 to v10.1.0 to leverage latest Swagger/OpenAPI features, security updates, and improved .NET 10 integration. This upgrade requires code refactoring due to breaking changes in the Microsoft.OpenApi v2.x dependency.

Current Status

• Current Version: Swashbuckle.AspNetCore v9.0.4
• Target Version: Swashbuckle.AspNetCore v10.1.0
• Status: Deferred from .NET 10 upgrade due to breaking changes
• Reason: Microsoft.OpenApi v2.x has API incompatibilities

Breaking Changes

Microsoft.OpenApi v2.x Changes

Swashbuckle v10 requires Microsoft.OpenApi >= 2.3.0, which has several breaking changes:

1. Namespace Structure: Potential changes in type locations
2. API Modifications: OpenApiInfo and related types may have different initialization patterns
3. Configuration API: Swagger configuration methods may have changed

Known Issues from .NET 10 Upgrade Attempt

Error Encountered:

CS0234: The type or namespace name 'Models' does not exist in the namespace 'Microsoft.OpenApi'

Affected File: RESTRunner.Web\Program.cs

Current Code (Swashbuckle v9):

using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "RESTRunner API", Version = "v1" });
    c.TagActionsBy(api =>
    {
        var path = api.RelativePath?.ToLower();
        if (path != null)
        {
            if (path.StartsWith("api/employees"))
                return new[] { "Employee" };
            if (path.StartsWith("api/departments"))
                return new[] { "Department" };
        }
        return new[] { "Other" };
    });
    c.DocInclusionPredicate((name, api) => true);
});

---

Research Phase (Before Implementation)

Tasks

1. Review Breaking Changes

   • Read Swashbuckle v10 release notes
   • Review Microsoft.OpenApi v2.x migration guide
   • Identify all affected code locations
   • Document required API changes

2. Analyze Current Usage

   • Audit all Microsoft.OpenApi usages in codebase
   • Document current swagger configuration
   • Identify custom swagger configurations
   • Check for any swagger middleware customizations

3. Create Migration Plan

   • Document step-by-step upgrade approach
   • Identify testing requirements
   • Plan rollback strategy
   • Estimate effort and timeline

---

Implementation Plan (After Research)

Phase 1: Update Packages (15 minutes)

1. Update Swashbuckle.AspNetCore to v10.1.0
2. Update Microsoft.OpenApi to v2.3.0 (or latest)
3. Resolve any package dependency conflicts
4. Document any additional required packages

Phase 2: Code Refactoring (60-120 minutes)

1. Update using statements in Program.cs

   • Fix namespace references for Microsoft.OpenApi v2.x
   • Update any deprecated imports

2. Refactor OpenApiInfo initialization

   • Update to Microsoft.OpenApi v2.x syntax
   • Verify all properties are correctly set

3. Update Swagger configuration

   • Modernize AddSwaggerGen configuration
   • Update TagActionsBy if API changed
   • Update DocInclusionPredicate if API changed
   • Verify custom configurations still work

4. Update middleware configuration (if needed)

   • Review UseSwagger() and UseSwaggerUI() calls
   • Update any custom middleware options

Phase 3: Testing & Validation (30-60 minutes)

Build Validation:

• Solution builds with 0 errors
• No new warnings introduced
• All existing tests pass (21/21)

Swagger UI Validation:

• Start web application: dotnet run in RESTRunner.Web
• Navigate to https://localhost:7001/swagger
• Verify Swagger UI loads correctly
• Test all API endpoints in Swagger UI
• Verify endpoint grouping (Employee, Department, Other tags)
• Test "Try it out" functionality for sample endpoints

API Documentation Validation:

• Verify OpenAPI spec generates correctly
• Check endpoint descriptions
• Verify request/response schemas
• Test parameter documentation
• Verify authentication documentation (if any)

Manual Web App Testing:

• Home page loads
• All Razor Pages render correctly
• Minimal APIs functional (/api/employees, /api/departments, /api/status)
• No console errors
• Theme switching still works

Phase 4: Documentation (15 minutes)

1. Update code comments if API usage changed
2. Document any new Swashbuckle v10 features utilized
3. Update developer documentation if needed
4. Create migration notes for future reference

---

Testing...

• Fixes Upgrade Swashbuckle.AspNetCore to v10 with Microsoft.OpenApi v2.x compatibility #3

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[markhazleton]

ok