Move from swagger to scalar #163
Conversation
WalkthroughMigration from Swagger to Scalar API documentation with addition of GraphQL extensibility hooks and SignalR hub configuration support in the Bootstrap class. Swagger extension removed and replaced with new Scalar extension module. GraphQL and documentation configuration now virtualized for extensibility. Changes
Sequence DiagramsequenceDiagram
participant Client
participant Bootstrap
participant DI as Dependency Injection
participant Scalar as Scalar Docs
participant GraphQL
participant SignalR
rect rgba(100, 200, 150, 0.2)
Note over Bootstrap,SignalR: Application Startup
Bootstrap->>DI: HasSignalRHubs()?
alt HasSignalRHubs = true
Bootstrap->>DI: Register SignalR Hubs
end
Bootstrap->>DI: GraphQLQueryType?
alt GraphQLQueryType != null
Bootstrap->>GraphQL: AddGraphQLWithDocumentation()
Bootstrap->>GraphQL: ConfigureGraphQL(builder)
end
Bootstrap->>DI: AddScalar + UseScalarDocumentation
Bootstrap->>Scalar: Configure with hubs & GraphQL metadata
end
rect rgba(150, 150, 200, 0.2)
Note over Client,Scalar: Runtime - API Documentation Access
Client->>Scalar: GET /docs
Scalar->>Scalar: BuildCustomDocumentationContent()
alt IncludeSignalR
Scalar->>SignalR: CreateWebSocketDocumentation()
end
alt IncludeGraphQL
Scalar->>GraphQL: CreateGraphQLDocumentation()
end
Scalar-->>Client: Unified API Documentation
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (5)
src/Simplic.OxS.Server/Simplic.OxS.Server.csproj (1)
20-30: Scalar/OpenAPI package references look consistent with the migrationAdding
Microsoft.AspNetCore.OpenApiandScalar.AspNetCorematches the move away from Swashbuckle and prepares for Scalar-based docs. Once the actual Scalar middleware/UI wiring is in place, these references should be exercised; if that work is postponed for a while, consider deferringScalar.AspNetCoreto avoid an unused dependency.src/Simplic.OxS.Server/SCALAR_MIGRATION.md (1)
1-3: Clean up stray??markers in headingsHeadings like “### ?? Package Changes”, “## ?? Documentation Features”, “## ?? Implementation Guide”, etc., contain literal
??which look like lost emoji/placeholders. Recommend either removing them or replacing them with explicit icons/text so the markdown renders cleanly.Also applies to: 37-38, 60-61, 151-152, 178-179, 186-187, 197-199, 203-205, 218-220
src/Simplic.OxS.Server/Extensions/GraphQLExtension.cs (1)
36-59: AddGraphQLWithDocumentation mirrors UseGraphQL; consider DRYing and clarifying “WithDocumentation”The new
AddGraphQLWithDocumentationcorrectly wires the same GraphQL server pipeline for a runtimeTypeand will work withBootstrap.GraphQLQueryType. However:
- Its body is almost identical to
UseGraphQL<TQuery>; extracting a small private helper taking the queryTypewould avoid duplication.- Despite the name, this method currently doesn’t add anything documentation-specific; all documentation integration is deferred to Scalar-related helpers. Either renaming it or adding the documentation-specific bits later would make the intent clearer.
src/Simplic.OxS.Server/Extensions/ScalarExtension.cs (2)
59-100: Consolidate ScalarOptions configuration and remove unused parameters
AddScalarcurrently:
- Ignores the
envparameter.- Populates options from
OpenApiInfoand forwards toAddScalarConfiguration.
AddScalarConfigurationthen creates a freshScalarOptionsinstance, applies the configuration, callsAddEndpointsApiExplorer, and registers the options singleton—but the rest of the code (e.g.,Bootstrap.Configure) then constructs anotherScalarOptionsinstance manually and passes it toUseScalarDocumentation.This means:
- The DI-registered
ScalarOptionsis not used anywhere.- Options are effectively configured twice in two disconnected code paths.
Consider:
- Dropping the unused
envargument fromAddScalar(or using it), and- Either reusing the DI-registered
ScalarOptionsinConfigure/UseScalarDocumentation, or removing the DI registration until you actually consume it.This will simplify the story around how Scalar is configured.
132-283: Helper documentation builders are currently unused and may drift from reality
BuildCustomDocumentationContent,CreateWebSocketDocumentation, andCreateGraphQLDocumentationconstruct rich documentation structures (Markdown content, SignalR hub metadata, GraphQL query metadata), but nothing in the current code calls them. As a result:
- Any future consumer of these helpers will need to reconcile their assumptions (e.g., endpoints like
/hubs/{hubName},/graphql,/graphql/playground) with the actual mapped routes andUsePathBasebehavior inBootstrap.- Until they are wired into the Scalar UI, they add untested surface area.
Either hook these helpers into whatever Scalar-based UI you plan to use (so they actively drive documentation), or leave them out until that integration is ready to avoid stale or misleading documentation metadata.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
src/Simplic.OxS.Server/Attributes/HideInDocumentation.cs(1 hunks)src/Simplic.OxS.Server/Bootstrap.cs(6 hunks)src/Simplic.OxS.Server/Extensions/GraphQLExtension.cs(2 hunks)src/Simplic.OxS.Server/Extensions/ScalarExtension.cs(1 hunks)src/Simplic.OxS.Server/Extensions/SwaggerExtension.cs(0 hunks)src/Simplic.OxS.Server/SCALAR_MIGRATION.md(1 hunks)src/Simplic.OxS.Server/Simplic.OxS.Server.csproj(3 hunks)
💤 Files with no reviewable changes (1)
- src/Simplic.OxS.Server/Extensions/SwaggerExtension.cs
🧰 Additional context used
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to {Program.cs,Startup.cs,**/Controllers/**/*.cs} : Implement API versioning and document with Swagger/OpenAPI (endpoints, parameters, responses, authentication)
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to {Program.cs,Startup.cs,**/Controllers/**/*.cs} : Implement API versioning and document with Swagger/OpenAPI (endpoints, parameters, responses, authentication)
Applied to files:
src/Simplic.OxS.Server/Simplic.OxS.Server.csprojsrc/Simplic.OxS.Server/Attributes/HideInDocumentation.cssrc/Simplic.OxS.Server/SCALAR_MIGRATION.mdsrc/Simplic.OxS.Server/Bootstrap.cssrc/Simplic.OxS.Server/Extensions/ScalarExtension.cs
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to **/*.cs : Prefer built-in ASP.NET Core features over third-party dependencies; document external dependencies and their purpose in comments
Applied to files:
src/Simplic.OxS.Server/Simplic.OxS.Server.csproj
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to {Program.cs,Startup.cs,**/Controllers/**/*.cs,**/Authorization/**/*.cs} : Use JWT Bearer authentication; support OAuth 2.0/OpenID Connect; role-based and policy-based authorization; integrate with Microsoft Entra ID; apply consistent security to controllers and minimal APIs
Applied to files:
src/Simplic.OxS.Server/Simplic.OxS.Server.csprojsrc/Simplic.OxS.Server/Bootstrap.cs
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to {Program.cs,**/Middleware/**/*.cs,**/Logging/**/*.cs,**/Telemetry/**/*.cs} : Use structured logging (e.g., Serilog), appropriate log levels, Application Insights integration, custom telemetry and correlation IDs; monitor performance, errors, usage
Applied to files:
src/Simplic.OxS.Server/Simplic.OxS.Server.csprojsrc/Simplic.OxS.Server/Bootstrap.cs
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to **/*.cs : Target ASP.NET Core (latest supported) for a web application
Applied to files:
src/Simplic.OxS.Server/Simplic.OxS.Server.csproj
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to **/*.cs : Add XML documentation comments (///) for public classes, methods, and properties with <summary>, <param>, <returns> and use <example>/<code> when beneficial
Applied to files:
src/Simplic.OxS.Server/Attributes/HideInDocumentation.cs
📚 Learning: 2025-08-26T05:52:00.195Z
Learnt from: CR
Repo: simplic/simplic-oxs-storage-management PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-26T05:52:00.195Z
Learning: Applies to **/*.cs : Use dependency injection for all services
Applied to files:
src/Simplic.OxS.Server/Bootstrap.cs
🧬 Code graph analysis (3)
src/Simplic.OxS.Server/Extensions/GraphQLExtension.cs (1)
src/Simplic.OxS.Server/Middleware/HttpRequestInterceptor.cs (1)
HttpRequestInterceptor(13-81)
src/Simplic.OxS.Server/Bootstrap.cs (5)
src/Simplic.OxS.Server/Implementations/ServiceDefinitionService.cs (2)
ServiceDefinitionService(10-119)Fill(17-79)src/Simplic.OxS.Server/Filter/RequestContextActionFilter.cs (2)
RequestContextActionFilter(10-113)RequestContextActionFilter(18-21)src/Simplic.OxS.Server/Filter/ValidationActionFilter.cs (1)
ValidationActionFilter(10-23)src/Simplic.OxS.Server/Filter/RequestContextHubFilter.cs (1)
RequestContextHubFilter(9-69)src/Simplic.OxS.Server/Extensions/ScalarExtension.cs (4)
ScalarOptions(13-24)ScalarContact(29-34)ScalarLicense(39-43)UseScalarDocumentation(108-125)
src/Simplic.OxS.Server/Extensions/ScalarExtension.cs (2)
src/Simplic.OxS.Server/Extensions/GraphQLExtension.cs (2)
IServiceCollection(16-34)IServiceCollection(43-59)src/Simplic.OxS.Server/Bootstrap.cs (2)
OpenApiInfo(256-276)Action(307-307)
🔇 Additional comments (7)
src/Simplic.OxS.Server/Attributes/HideInDocumentation.cs (1)
3-5: Documentation update appropriately aligns with Swagger-to-Scalar migration.The change from "swagger documentation" to "API documentation" is fitting for the migration and makes the documentation more implementation-agnostic. The summary clearly conveys the attribute's purpose.
src/Simplic.OxS.Server/Simplic.OxS.Server.csproj (1)
50-52: Sample folder inclusion is fineIncluding a
Sample\folder in the project is a clear place for reference implementations of the new Scalar setup; no issues from a build/runtime perspective.src/Simplic.OxS.Server/Extensions/GraphQLExtension.cs (1)
16-34: Generic GraphQL registration change is backward compatibleMaking the
builderparameter optional while keeping the same pipeline (interceptor, authorization, TimeSpan type, MongoDB providers) preserves existing behavior and adds flexibility for callers that don’t need extra configuration. No concerns here.src/Simplic.OxS.Server/Bootstrap.cs (4)
71-82: Authorization defaults and newJwtOnlypolicy look sensibleUsing JWT + ApiKey in the default policy and adding an explicit
JwtOnlypolicy gives you flexibility to tighten auth on specific endpoints while preserving current behavior elsewhere. This aligns well with the existing RequestContext logic and doesn’t introduce obvious regressions.
108-148: Service definition, GraphQL, controllers, and SignalR wiring are coherent
- Registering
ServiceDefinitionServiceas a singleton and callingFill()immediately ensures the service definition is built once and reused.- Conditional GraphQL registration via
GraphQLQueryType+ConfigureGraphQLgives derived services a straightforward opt-in path.- Applying
RequestContextActionFilterandValidationActionFilterglobally throughMvcBuilder(services.AddControllers(...))centralizes common concerns.- SignalR is always registered with
RequestContextHubFilter, and redis backplane is added when a connection string is present.Overall this block hangs together well and fits the existing abstractions.
206-219: Endpoint mapping with optional GraphQL is straightforwardUsing
UseEndpointsto map controllers, hubs (viaMapHubs), additional endpoints (MapEndpoints), and conditionallyMapGraphQL()based onGraphQLQueryTypemakes the graph of reachable endpoints explicit and extensible for derived services. No issues here.
246-252: GraphQL and SignalR extensibility hooks are well-designedThe new virtuals:
ConfigureGraphQL(IRequestExecutorBuilder builder)as a customization hook, andGraphQLQueryType/HasSignalRHubs()as feature togglesgive derived bootstrap classes a clear, discoverable way to opt into GraphQL and to declare whether SignalR hubs exist for documentation purposes. Signatures and defaults are reasonable.
Also applies to: 309-323
| // Configure Scalar API documentation | ||
| var scalarOptions = new ScalarOptions | ||
| { | ||
| c.PreSerializeFilters.Add((swagger, httpReq) => | ||
| ApiVersion = ApiVersion, | ||
| Title = GetApiInformation().Title, | ||
| Description = GetApiInformation().Description ?? "API Documentation", | ||
| Contact = new ScalarContact | ||
| { | ||
| if (env.IsDevelopment()) | ||
| { | ||
| swagger.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}{basePath}" } }; | ||
| } | ||
| else | ||
| { | ||
| swagger.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"https://{httpReq.Host.Value}{basePath}" } }; | ||
| } | ||
| }); | ||
| }); | ||
|
|
||
| app.UseSwaggerUI(c => | ||
| { | ||
| c.SwaggerEndpoint($"{basePath}/swagger/{ApiVersion}/swagger.json", $"Simplic.OxS.{ServiceName} {ApiVersion}"); | ||
| c.SwaggerEndpoint($"{basePath}/swagger/{ApiVersion}-SignalR/swagger.json", $"Simplic.OxS.{ServiceName} {ApiVersion}-SignalR"); | ||
| }); | ||
| Name = GetApiInformation().Contact?.Name, | ||
| Email = GetApiInformation().Contact?.Email, | ||
| Url = GetApiInformation().Contact?.Url?.ToString() | ||
| }, | ||
| License = new ScalarLicense | ||
| { | ||
| Name = GetApiInformation().License?.Name, | ||
| Url = GetApiInformation().License?.Url?.ToString() | ||
| }, | ||
| TermsOfService = GetApiInformation().TermsOfService?.ToString(), | ||
| BasePath = basePath, | ||
| IncludeSignalR = HasSignalRHubs(), | ||
| IncludeGraphQL = GraphQLQueryType != null | ||
| }; | ||
|
|
||
| app.UseScalarDocumentation(scalarOptions, env); | ||
|
|
There was a problem hiding this comment.
Scalar options wiring is fine, but you’re still missing actual documentation endpoints
The ScalarOptions object is populated consistently (version, title, description, contact, license, base path, GraphQL/SignalR flags) and passed into UseScalarDocumentation. However, UseScalarDocumentation currently only writes to the console and does not expose a Scalar UI or OpenAPI endpoint; Swagger/SwaggerUI has been removed elsewhere.
Net effect from consumers’ point of view is that interactive API documentation endpoints disappear. Either wire the real documentation endpoints (e.g., via OpenAPI + Scalar UI) or clearly treat this as an intermediate step and keep Swagger until Scalar is fully hooked up.
🤖 Prompt for AI Agents
In src/Simplic.OxS.Server/Bootstrap.cs around lines 166-190, the ScalarOptions
are built and passed to UseScalarDocumentation but no actual documentation
endpoints or UI are registered; restore or wire up real docs so consumers still
get interactive docs. Either (A) re-enable the OpenAPI/Swagger middleware (e.g.,
app.UseSwagger(); app.UseSwaggerUI(...)) until Scalar’s UI/OpenAPI endpoints are
implemented, or (B) extend UseScalarDocumentation to register and map the actual
endpoints (OpenAPI JSON endpoint and a Scalar UI route) and ensure those routes
use the same ScalarOptions/BasePath; update Startup/Program pipeline to call
these middleware and serve static assets if needed so the interactive
documentation remains available.
| /// <summary> | ||
| /// Configure Scalar UI in the application pipeline | ||
| /// </summary> | ||
| /// <param name="app">Application builder</param> | ||
| /// <param name="options">Scalar configuration options</param> | ||
| /// <param name="env">Web host environment</param> | ||
| internal static void UseScalarDocumentation(this IApplicationBuilder app, ScalarOptions options, IWebHostEnvironment env) | ||
| { | ||
| // For now, provide a simple message that Scalar documentation is configured | ||
| // This can be enhanced when the proper Scalar setup is available | ||
| Console.WriteLine($"? Scalar API Documentation configured for {options.Title}"); | ||
| Console.WriteLine($" - Version: {options.ApiVersion}"); | ||
| Console.WriteLine($" - Base Path: {options.BasePath}"); | ||
|
|
||
| if (options.IncludeGraphQL) | ||
| { | ||
| Console.WriteLine(" - GraphQL endpoint: /graphql"); | ||
| } | ||
|
|
||
| if (options.IncludeSignalR) | ||
| { | ||
| Console.WriteLine(" - SignalR hubs: Configured"); | ||
| } | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
UseScalarDocumentation only logs; no Scalar/OpenAPI endpoints are exposed
UseScalarDocumentation currently just writes a few informational lines to the console and does not:
- Configure any Scalar UI middleware, or
- Map any OpenAPI endpoints.
Given that Swagger/SwaggerUI has been removed, this means API documentation is no longer available over HTTP, which is a behavior regression relative to the previous setup and contradicts the migration doc that advertises new Scalar endpoints.
I’d strongly recommend wiring in the real documentation pipeline (OpenAPI + Scalar UI) before relying on this extension, or keeping Swagger in place until that wiring is implemented.
Please double‑check the intended Scalar/OpenAPI integration against the Scalar.AspNetCore and Microsoft.AspNetCore.OpenApi documentation to ensure the final design exposes the documented endpoints.
I'll verify the review comment by examining the codebase structure and configuration. Let me start by exploring the relevant files.
---
🏁 Script executed:
```shell
#!/bin/bash
# Examine the full ScalarExtension.cs file
cat src/Simplic.OxS.Server/Extensions/ScalarExtension.cs
Length of output: 8896
🏁 Script executed:
#!/bin/bash
# Search for Swagger or OpenAPI configuration elsewhere in the codebase
rg -n -i "swagger|openapi|scalar" --type=cs -C 3 | head -100Length of output: 8138
🏁 Script executed:
#!/bin/bash
# Search for middleware configuration in Startup or Program files
fd -e cs | xargs grep -l "UseSwagger\|UseOpenApi\|UseScalar\|AddSwagger\|AddOpenApi" 2>/dev/null | head -20Length of output: 88
🏁 Script executed:
#!/bin/bash
# Look for service registration patterns (AddScalar, AddOpenApi, AddSwagger)
rg -n "Add.*Swagger|Add.*OpenApi|Add.*Scalar" --type=cs -C 2Length of output: 2681
Now let me verify the proper setup pattern for Scalar.AspNetCore and OpenAPI integration:
🌐 Web query:
Scalar.AspNetCore setup middleware configuration example
💡 Result:
Here are minimal Program.cs examples showing how to add Scalar.AspNetCore for the common OpenAPI generators.
- Microsoft.AspNetCore.OpenApi (recommended new minimal approach)
- Install: dotnet add package Scalar.AspNetCore
- Program.cs:
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.MapOpenApi(); // exposes /openapi/{documentName}.json
app.MapScalarApiReference(); // maps the Scalar UI at /scalar
}
app.UseHttpsRedirection();
app.MapControllers();
app.Run();
- Swashbuckle (SwaggerGen)
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger(options => { options.RouteTemplate = "/openapi/{documentName}.json"; });
app.MapScalarApiReference(); // map Scalar UI (default /scalar)
}
app.UseHttpsRedirection();
app.MapControllers();
app.Run();
Notes
- Put Scalar mapping (MapScalarApiReference) behind an environment check (Development) for production safety.
- You can pass options to MapScalarApiReference/MapScalarApiReference(...) to set Title, Theme, default client, etc.
Sources:
- Scalar .NET integration docs (examples for Microsoft.OpenApi / Swashbuckle). [1]
- AspNetCore.Scalar GitHub README (simple UseScalar / MapScalarApiReference example). [2]
References:
[1] https://guides.scalar.com/scalar/scalar-api-references/integrations/net-aspnet-core
[2] https://github.com/benirave/aspnetcore.scalar
🌐 Web query:
Microsoft.AspNetCore.OpenApi UseOpenApi middleware setup
💡 Result:
Short answer — use the Microsoft.AspNetCore.OpenApi package and call AddOpenApi() and MapOpenApi() (the package exposes an endpoint via MapOpenApi; there is no UseOpenApi middleware). Example:
-
Install
dotnet add package Microsoft.AspNetCore.OpenApi. [1] -
Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi(); // register OpenAPI services. [2]var app = builder.Build();
app.MapOpenApi(); // registers /openapi/{name}.json endpoint. [2][3]// optional: treat the OpenAPI route like any endpoint (cache, authorize, etc.)
// e.g. app.MapOpenApi().RequireAuthorization(); [4]app.MapGet("/", () => "Hello");
app.Run();
Notes:
- The package generates the OpenAPI JSON document; it does not include a built‑in UI. Use Swashbuckle/Swagger UI or another UI if you need human-friendly docs. [2][3]
- The WithOpenApi endpoint helper was used historically for per-endpoint operation metadata and is deprecated in newer runtimes (.NET 10+). Remove/migrate calls accordingly. [5]
Sources:
[1] NuGet: Microsoft.AspNetCore.OpenApi.
[2] .NET blog: OpenAPI document generation in .NET 9 (AddOpenApi / MapOpenApi).
[3] Community blog / migration posts about MapOpenApi registering /openapi/v1.json.
[4] Example showing endpoint metadata usage (MapOpenApi as endpoint).
[5] Microsoft compatibility note: WithOpenApi deprecation.
Wire in OpenAPI document generation and Scalar UI middleware endpoints
UseScalarDocumentation() currently only logs to the console. The following are missing:
- AddOpenApi() service registration and MapOpenApi() endpoint mapping to expose the OpenAPI document
- MapScalarApiReference() middleware call to expose the Scalar UI
Additionally, AddScalar() only registers AddEndpointsApiExplorer(), which is insufficient without the OpenAPI document generator itself. The helper methods (BuildCustomDocumentationContent, CreateWebSocketDocumentation, CreateGraphQLDocumentation) are defined but never invoked.
Required fixes:
- In
AddScalar()/AddScalarConfiguration(): Addservices.AddOpenApi()(orservices.AddSwaggerGen()if using Swashbuckle) - In
UseScalarDocumentation(): Callapp.MapOpenApi()andapp.MapScalarApiReference()to expose the endpoints
This blocks API documentation availability over HTTP, which is a regression relative to the previous setup.
🤖 Prompt for AI Agents
src/Simplic.OxS.Server/Extensions/ScalarExtension.cs around lines 102-125:
UseScalarDocumentation currently only writes console messages and does not
expose OpenAPI/Scalar UI endpoints; update the startup wiring to call the
OpenAPI generator and map the endpoints — in the
AddScalar/AddScalarConfiguration registration add services.AddOpenApi() (or
services.AddSwaggerGen() if using Swashbuckle) in addition to
AddEndpointsApiExplorer(), and ensure the helper doc builders
(BuildCustomDocumentationContent, CreateWebSocketDocumentation,
CreateGraphQLDocumentation) are invoked when building the OpenAPI document; in
UseScalarDocumentation replace the console-only behavior by calling
app.MapOpenApi() and app.MapScalarApiReference() (and map GraphQL/SignalR doc
endpoints when IncludeGraphQL/IncludeSignalR are true) so the OpenAPI JSON and
Scalar UI are served over HTTP.
| ### ?? Package Changes | ||
|
|
||
| **Removed:** | ||
| - `Swashbuckle.AspNetCore` - Replaced with modern alternatives | ||
| - `SignalRSwaggerGen` - Integrated into custom Scalar documentation | ||
|
|
||
| **Added:** | ||
| - `Scalar.AspNetCore` (v1.2.42) - Modern API documentation UI | ||
| - `Microsoft.AspNetCore.OpenApi` (v8.0.2) - .NET 8 native OpenAPI support | ||
|
|
||
| ### ?? Code Changes |
There was a problem hiding this comment.
Align “Package/Code Changes” section with the actual API surface
The doc mentions services.AddScalar() and app.UseScalar() replacements, but the code currently exposes AddScalar(...) and UseScalarDocumentation(...) (see Bootstrap and ScalarExtension). Also, the Scalar integration at this point is only configuring options/logging and does not yet wire a UI or OpenAPI endpoints. Please either (a) update the code to match the promised API and behavior, or (b) tone down this section to describe the current transitional state more accurately.
🤖 Prompt for AI Agents
In src/Simplic.OxS.Server/SCALAR_MIGRATION.md around lines 11 to 21, the docs
claim services.AddScalar() and app.UseScalar() and a UI/OpenAPI endpoint but the
code currently exposes AddScalar(...) and UseScalarDocumentation(...) and only
configures options/logging; either update the code to match the docs by
renaming/adding the public extension methods to AddScalar and UseScalar (or add
forwarding overloads that call existing AddScalar(...) and
UseScalarDocumentation(...)) and implement wiring for the UI/OpenAPI endpoints,
or change the markdown to accurately describe the transitional state by using
the real method names (AddScalar(...), UseScalarDocumentation(...)) and noting
that only options/logging are configured and no UI/OpenAPI endpoints are
registered yet.
| ## ?? Documentation Features | ||
|
|
||
| ### REST API Documentation | ||
| - **OpenAPI/Swagger compatible** - Maintains full compatibility with existing OpenAPI specifications | ||
| - **Interactive interface** - Modern, fast, and responsive documentation UI | ||
| - **Authentication support** - JWT Bearer and API Key authentication documented | ||
| - **Request/Response examples** - Comprehensive examples for all endpoints | ||
| - **Model schemas** - Detailed schema documentation for all data models | ||
|
|
||
| ### GraphQL Documentation | ||
| - **Integrated GraphQL playground** - Access at `/graphql/ui` (development only) | ||
| - **Schema introspection** - Full GraphQL schema documentation | ||
| - **Query examples** - Sample queries and mutations | ||
| - **Type system documentation** - Complete type documentation | ||
| - **Real-time subscriptions** - WebSocket-based subscriptions support | ||
|
|
||
| ### WebSocket Documentation (SignalR) | ||
| - **Hub documentation** - Automatic documentation of SignalR hubs | ||
| - **Method signatures** - Parameter and return type documentation | ||
| - **Connection examples** - JavaScript and .NET client examples | ||
| - **Authentication guidance** - JWT token integration examples | ||
| - **Group management** - Documentation for group-based messaging | ||
|
|
There was a problem hiding this comment.
Documented documentation endpoints and features don’t yet exist in code
Sections “Documentation Features”, “Access Points”, and the SignalR/GraphQL docs claim:
- automatic SignalR hub documentation,
- a main Scalar UI at
/{service-name}-api/{version}/scalar/v1, - an OpenAPI spec at
/openapi/v1.json, - GraphQL playground at
/graphql/ui(and later/graphql).
In the current implementation, UseScalarDocumentation only writes console messages and no HTTP endpoints are mapped, nor is Microsoft.AspNetCore.OpenApi or Scalar.AspNetCore wired to expose these URLs. This will mislead users following the guide. I’d suggest either implementing the described endpoints now or clearly marking them as planned/target behavior and documenting what is actually available today.
Also applies to: 178-185
🤖 Prompt for AI Agents
In src/Simplic.OxS.Server/SCALAR_MIGRATION.md around lines 37–59 (and also apply
to lines 178–185), the doc claims HTTP endpoints and UI (SignalR hub docs,
/{service-name}-api/{version}/scalar/v1, /openapi/v1.json, /graphql/ui) exist
but the code currently only writes console messages; either implement the
endpoints or mark them as planned — to implement: add and register
Microsoft.AspNetCore.OpenApi and Scalar.AspNetCore packages, wire up
OpenAPI/Swagger generation in Program.cs/Startup, map the OpenAPI JSON and
Swagger UI endpoints, enable and map the GraphQL playground endpoint and GraphQL
middleware, and ensure SignalR hub documentation middleware is registered and
hub routes are mapped; alternatively, update UseScalarDocumentation to return
actual endpoint URLs and change the markdown to clearly label these features as
"planned/not yet implemented" with instructions for where code will be added.
Summary by CodeRabbit
Release Notes
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.