Swagger
The SimpleW.Helper.Swagger package provides Swagger / OpenAPI documentation support for the SimpleW web server.
It automatically generates an OpenAPI 3.0 specification from the routes and handlers registered in SimpleW, and exposes a built-in Swagger UI for API exploration.
Swagger is exposed as a helper, not a module: you decide where, how, and under which security rules it is served.
This package works without ASP.NET, without annotations, and without modifying the SimpleW core.
Features
It allows you to :
- Generate an OpenAPI 3.0 JSON document automatically
- Infer paths, HTTP methods, and parameters from registered routes
- Detect path parameters
- Support both controller-based and delegate-based routes
- Serve a built-in Swagger UI directly from SimpleW
- Filter which routes appear in the documentation
Requirements
- .NET 8.0
- SimpleW (core server)
No external dependencies.
Installation
$ dotnet add package SimpleW.Helper.Swagger --version 26.0.0-rc.20260202-1339Configuration options
| Option | Default | Description |
|---|---|---|
| Title | "SimpleW API" | OpenAPI document title (info.title). Empty or whitespace values are normalized back to the default. |
| Version | "v1" | OpenAPI version string (info.version). Empty or whitespace values are normalized back to the default. |
| Description | null | Optional OpenAPI description (info.description). |
| RouteFilter | null | Optional predicate used to filter which routes are included in the generated OpenAPI document. null means all registered routes are included. |
| ScanControllersForParameters | true | When enabled, controller methods are scanned to infer query parameter types (best-effort reflection). |
| UiHtmlFactory | null | Optional factory to fully customize the Swagger UI HTML page. Receives the generated OpenAPI JSON string and must return the final HTML. If null, the built-in Swagger UI template is used. |
Minimal Example
using System.Net;
using SimpleW;
using SimpleW.Helper.Swagger;
var server = new SimpleWServer(IPAddress.Any, 8080);
server.MapGet("/api/hello", (string name) => {
return new { message = $"Hello {name}" };
});
// OpenAPI JSON
server.MapGet("/swagger.json", static (HttpSession session) => {
return Swagger.Json(session);
});
// Swagger UI
server.MapGet("/swagger", static (HttpSession session) => {
return Swagger.UI(session);
});
await server.RunAsync();Nothing is registered automatically. You explicitly choose where Swagger lives.
Route discovery
The Swagger package automatically discovers routes from the SimpleW router.
Supported styles :
MapGet,MapPost,Map(method, path, handler)- Controller-based routing using
[Route]attributes
Path parameters
Path parameters are detected from route templates :
server.MapGet("/api/users/:id", (int id) => {
return new { id };
});This produces :
GET /api/users/{id}With id documented as a path parameter.
Controller-based routes
Controllers are supported automatically.
[Route("/api/users")]
public sealed class UsersController : Controller {
[Route("GET", "/list")]
public object List(int page = 1) {
return new { page };
}
}The Swagger helper inspects controller methods via reflection and infers parameters from their signatures.
Swagger UI
Swagger UI is returned explicitly by the helper. There is no default route and no fixed path.
Example :
server.MapGet("/swagger", static (HttpSession session) => {
return Swagger.UI(session);
});The UI uses a CDN-based Swagger UI distribution by default. No static files are required.
You can override the UI HTML if needed :
server.MapGet("/swagger", static (HttpSession session) => {
return Swagger.UI(session, options => {
options.UiHtmlFactory = jsonContent => $"<html>Custom UI for {jsonContent}</html>";
});
});OpenAPI generation behavior
- OpenAPI version : 3.0.3
- Responses :
200is generated by default
- Schemas :
- Primitive parameter types are inferred when possible
- Complex request/response schemas are not generated automatically (by design)
The goal is accurate route documentation, not full schema generation.