refactor(api): migrate Swashbuckle to Scalar + chore(deps): upgrade NuGet packages#35
Merged
Merged
Conversation
…tCore.OpenApi + Scalar - Drop Swashbuckle.AspNetCore; add Microsoft.AspNetCore.OpenApi (10.0.7) and Scalar.AspNetCore (2.14.14). - Delete ConfigureSwaggerOptions.cs and SwaggerDefaultValues.cs. - New OpenApiDocumentTransformers.cs: - VersionedInfoDocumentTransformer: per-version OpenApiInfo (title, version, contact, license, deprecation/sunset text). - BearerSecurityDocumentTransformer: JWT Bearer scheme + document-wide security requirement. - DependencyInjection.AddVersionedOpenApi enumerates IApiVersionDescriptionProvider.ApiVersionDescriptions and registers one OpenAPI document per version with both transformers. - Program.cs: replace UseSwagger()/UseSwaggerUI(...) with MapOpenApi() + MapScalarApiReference(...); each version registered as a Scalar document, Bearer set as preferred security scheme. - launchSettings.json: launchUrl set to scalar/ on InMemory and CosmosDb profiles. - README: reference Scalar instead of Swashbuckle/UseSwaggerUI. Verified: build clean (0/0), all 122 tests pass, GET /openapi/2022-10-01.json returns 200 with Bearer scheme + global requirement, GET /scalar/ renders against the right document.
Bumps all packages to their latest stable versions, with three documented pins: - Asp.Versioning.Mvc.ApiExplorer 8.1.0 (was already pinned). 8.1.1 has a confirmed regression in the Rfc7231ProblemDetailsWriter wrapper that hijacks problem-details writer ordering and silently drops bodies (dotnet/aspnet-api-versioning#1191, fixed in 10.0.0). 10.x removes the wrapper but exposes a latent ASP.NET Core MVC issue with this repo's <AssemblyAttribute Include="...ApiController"/> setup — tracked for a follow-up PR. - FluentAssertions 7.2.2: v8.0+ switched to a paid commercial license (XCEED Software). 7.2.2 is the last MIT-licensed release. - Xunit.DependencyInjection 9.3.0: v10+ switched to xunit.v3, which collides with xunit 2.x. Bumped: Azure.Identity 1.13.2 -> 1.21.0 FluentValidation 11.3.0 -> 12.1.1 Mapster / Mapster.DependencyInjection 7.4 / 1.0 -> 10.0.7 Microsoft.AspNetCore.Authentication.JwtBearer 10.0.0 -> 10.0.8 Microsoft.AspNetCore.Mvc.Testing 10.0.0 -> 10.0.8 Microsoft.AspNetCore.OpenApi 10.0.7 -> 10.0.8 Microsoft.Azure.Cosmos 3.46.1 -> 3.61.0 Microsoft.Extensions.Configuration 10.0.0 -> 10.0.8 Microsoft.Extensions.Options.ConfigurationExtensions 10.0.0 -> 10.0.8 Nerdbank.GitVersioning 3.7.115 -> 3.9.50 Newtonsoft.Json 13.0.3 -> 13.0.4 System.IdentityModel.Tokens.Jwt 8.3.1 -> 8.19.1 coverlet.collector 6.0.4 -> 10.0.1 Microsoft.NET.Test.Sdk 17.10.0 -> 18.6.0 xunit 2.8.0 -> 2.9.3 xunit.runner.visualstudio 2.8.0 -> 3.1.5 xunit.categories 2.0.8 -> 3.0.1 Verified: 0 warnings, 0 errors, 122/122 tests pass.
xavierjohn
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrate the API service from Swashbuckle (Swagger UI) to
Microsoft.AspNetCore.OpenApi+ Scalar, and refresh all NuGet packages to their latest stable versions.Commits
6ee3353refactor(api): migrate from Swashbuckle/Swagger UI to Microsoft.AspNetCore.OpenApi + Scalaraae3c2cchore(deps): upgrade NuGet packages to latestScalar migration
Packages
Swashbuckle.AspNetCoreMicrosoft.AspNetCore.OpenApi(already centralised)Scalar.AspNetCore2.14.14Files
Api/src/ConfigureSwaggerOptions.cs,Api/src/SwaggerDefaultValues.csApi/src/OpenApiDocumentTransformers.cs(VersionedInfoDocumentTransformer+BearerSecurityDocumentTransformer)Api/src/DependencyInjection.cs— newAddVersionedOpenApi()enumeratesIApiVersionDescriptionProvider.ApiVersionDescriptionsand registers one OpenAPI document per version with both transformersApi/src/Program.cs—UseSwagger()+UseSwaggerUI(...)→MapOpenApi()+MapScalarApiReference(...); each version registered as a Scalar document,Bearerset as preferred security schemeApi/src/Properties/launchSettings.json—launchUrl: ""scalar/""onInMemoryandCosmosDbprofilesREADME.md— references Scalar instead of Swashbuckle/UseSwaggerUI()XML doc comments still surface in the spec (
GenerateDocumentationFileis on;Microsoft.AspNetCore.OpenApidiscovers the XML file automatically).Package upgrades
All packages bumped to latest stable, with three documented pins (inline comments in
Directory.Packages.props):Asp.Versioning.Mvc.ApiExplorer8.1.0 — 8.1.1 has a confirmedRfc7231ProblemDetailsWriterregression that hijacks problem-details writer ordering and silently drops bodies (dotnet/aspnet-api-versioning#1191, closed as fixed in 10.0.0). 10.x removes the wrapper but exposes a latent ASP.NET Core MVC issue (DefaultApiProblemDetailsWritersilently no-ops whenIApiBehaviorMetadatais missing from endpoint metadata, which happens with this repo's<AssemblyAttribute Include=""...ApiController""/>setup). Tracked for a follow-up.FluentAssertions7.2.2 — v8.0+ switched to a paid commercial license (XCEED Software). 7.2.2 is the last MIT-licensed release.Xunit.DependencyInjection9.3.0 — v10+ switched to xunit.v3, which collides with xunit 2.x.Bumped:
Azure.Identity 1.13.2 → 1.21.0,FluentValidation 11.3.0 → 12.1.1,Mapster / Mapster.DependencyInjection 7.4 / 1.0 → 10.0.7,Microsoft.AspNetCore.* 10.0.0 → 10.0.8,Microsoft.AspNetCore.OpenApi 10.0.7 → 10.0.8,Microsoft.Azure.Cosmos 3.46.1 → 3.61.0,Microsoft.Extensions.* 10.0.0 → 10.0.8,Nerdbank.GitVersioning 3.7 → 3.9.50,Newtonsoft.Json 13.0.3 → 13.0.4,System.IdentityModel.Tokens.Jwt 8.3.1 → 8.19.1,coverlet.collector 6.0.4 → 10.0.1,Microsoft.NET.Test.Sdk 17.10.0 → 18.6.0,xunit 2.8.0 → 2.9.3,xunit.runner.visualstudio 2.8.0 → 3.1.5,xunit.categories 2.0.8 → 3.0.1.Verification
dotnet build: 0 warnings, 0 errors.dotnet test: 122/122 pass (Domain 45 · Application 1 · Infrastructure 2 · Api 74), three consecutive runs.GET /openapi/2022-10-01.json→200withinfo.title=Buber Dinner,components.securitySchemes.Bearerpopulated, globalsecurity: [{ Bearer: [] }].GET /scalar/→200and referencesopenapi/2022-10-01.json.POST /authentication/login(bad creds) →401with properapplication/problem+jsonbody +WWW-Authenticate: Bearer.POST /authentication/register(happy path) → JWT issued.