Hi all,
Origam.Architect.Server currently exposes its API reference through Swashbuckle’s Swagger UI, enabled in the Development environment only. I’d like to suggest swapping that UI layer for Scalar.
Why it’s worth considering
- Swagger UI is no longer the default direction in ASP.NET Core. Since .NET 9, the Web API templates no longer ship Swashbuckle; Microsoft’s own OpenAPI documentation now points at third-party UIs, with Scalar being the most commonly referenced one. Staying on Swagger UI means drifting further from where the platform tooling is heading.
- The Architect API is large enough that UI quality matters. There are currently 13 controllers and roughly 58 endpoints, many of them with deeply nested request/response models (editor properties, tree nodes, wizard payloads). Swagger UI’s accordion layout and its model expander get unpleasant at that size. Scalar gives a searchable sidebar, persistent deep links to individual operations, and far more readable schema rendering — which is exactly where the time goes when someone is exploring the Architect API.
- Better request ergonomics for the people actually using it. Scalar generates ready-to-paste client snippets (curl, C#, JavaScript, and others) per endpoint and keeps a request history. For debugging the Architect frontend against the backend, that is a meaningful step up from Swagger UI’s “Try it out”.
- It’s a UI-only change with a very small blast radius. The OpenAPI document generation stays exactly as it is — the same generator, the same
swagger.json. Nothing about the contract, the controllers, or the serialization changes; only the page that renders the document. Because the whole thing is behind the Development-environment guard, production deployments are unaffected either way. - It decouples the two halves for the future .NET upgrade. The project targets net8.0, so the document generator has to stay as-is for now. But once the Architect moves to .NET 9+, the generator can be switched to the built-in
Microsoft.AspNetCore.OpenApiwithout touching the UI again. Doing the UI swap now means that later upgrade is a one-line change rather than a second migration. - Dark mode. Minor, but the Architect frontend has one and the API reference sitting next to it does not.
Would this be worth doing, or is there a reason to stay on Swagger UI here? If the preference is to wait until the Architect server moves to .NET 9 and do both changes at once, that seems reasonable too — I’ll leave the timing judgement to the maintainers.
Thanks!