ApiDocs.AspNetCore 1.2.0

ApiDocs.AspNetCore

One-line, branded, fully self-contained OpenAPI docs portal for ASP.NET Core services. Serves a branded Scalar interactive reference and the raw Swagger UI over your existing /swagger/v1/swagger.json — with both browser bundles vendored as embedded resources (no CDN, CSP-safe).

This is the reusable version of the hand-built AMLService docs portal: same polished shell, but themeable per service and with the Scalar/Swagger assets shipped inside the package instead of loaded from cdn.jsdelivr.net.

Why

• Consistent — every service exposes the same polished reference with one line.
• Self-contained / CSP-safe — the served HTML references no external host. Scalar is configured with withDefaultFonts:false + empty proxyUrl; Swagger UI with validatorUrl:null; all assets are served same-origin from the package.
• Branded — title, colours, logo, eyebrow, deep-dive guide pages, extra nav links.
• Swagger too — the classic Swagger UI is served alongside the branded reference.

Install

<PackageReference Include="ApiDocs.AspNetCore" Version="1.0.0" />

Quick start (adoption snippet)

The service must already produce an OpenAPI document at /swagger/v1/swagger.json (FastEndpoints.Swagger / NSwag / Swashbuckle — anything that serves the JSON spec).

using ApiDocs.AspNetCore.Configuration;
using ApiDocs.AspNetCore.Extensions;

var app = builder.Build();

// ... your middleware / endpoints ...

app.MapApiDocs(new ApiDocsOptions
{
    Title = "Kefi API",
    ServiceName = "Kefi",
    Eyebrow = "Developer docs",
    Description = "The Kefi events API — surveys, tickets, payments.",
    BrandColor = "#7c3aed",            // --accent
    BrandColorSecondary = "#14b8a6",   // --accent-2
    SpecUrl = "/swagger/v1/swagger.json",
    // AuthMode = ApiDocsAuthMode.RequireAuthInProduction  // default
});

app.Run();

That serves:

Both renderers read the same SpecUrl.

Bind from configuration instead

builder.AddApiDocs(opts => opts.Title = "Kefi API"); // binds the "ApiDocs" section + overrides
...
app.MapApiDocs(); // resolves the bound options from DI

// appsettings.json
"ApiDocs": {
  "Title": "Kefi API",
  "ServiceName": "Kefi",
  "BrandColor": "#7c3aed",
  "SpecUrl": "/swagger/v1/swagger.json"
}

Options (ApiDocsOptions)

Auth gating

AuthMode defaults to RequireAuthInProduction, mirroring the platform posture (e.g. kefi's /swagger returns 401 in prod, open in dev/staging):

• AlwaysOpen — open in every environment (public API products).
• RequireAuthInProduction — open in Development/Staging, requires authorization in Production (IHostEnvironment.IsProduction()).
• AlwaysRequireAuth — requires authorization everywhere.

When auth is required the docs group calls RequireAuthorization() (or your AuthorizationPolicy); otherwise it calls AllowAnonymous() so a global auth fallback doesn't accidentally gate the docs.

Route conflicts

SwaggerUiRoute defaults to /swagger-ui (not /swagger) so it does not collide with services that already serve NSwag's UI at /swagger. Set it to /swagger only for a service that doesn't already own that route.

Vendored assets

All are embedded in the assembly — the consuming service copies nothing to wwwroot.

License

MIT