Swagger / OpenAPI

GrydSwagger provides centralized Swagger/OpenAPI configuration with automatic JWT token management for the Gryd.IO ecosystem.

Features

Feature	Description
Bearer JWT Security	SecuritySchemeType.Http with Bearer scheme
Per-endpoint Lock Icons	Lock icon only on [Authorize] endpoints
Auto Token Capture	Automatically captures JWT from login response
Token Persistence	Preserves token across page refreshes
XML Comments	Auto-discovers XML documentation from assemblies

Quick Setup

// Program.cs
using Gryd.API.Swagger;

// Register services
builder.Services.AddGrydSwagger();

// Configure middleware
if (app.Environment.IsDevelopment())
{
    app.UseGrydSwagger();
}

That's it! With two lines you get a fully configured Swagger UI with automatic token management.

How Auto Token Capture Works

Configuration Options

Basic Configuration

builder.Services.AddGrydSwagger(options =>
{
    options.Title = "My API";
    options.Version = "v1";
    options.Description = "My application API documentation";
});

Full Configuration

builder.Services.AddGrydSwagger(options =>
{
    // API Documentation
    options.Title = "My Company API";
    options.Version = "v2";
    options.Description = "Complete API documentation";
    
    // Authentication
    options.IncludeAuthentication = true;   // Enable Bearer JWT (default: true)
    options.AutoCaptureToken = true;        // Auto-capture from login (default: true)
    options.PersistAuthorization = true;    // Keep token on refresh (default: true)
    
    // Custom login endpoint (relative path, version prefix added automatically)
    options.LoginEndpointPath = "auth/login";           // default
    options.TokenJsonPath = "data.token";               // default
    
    // XML Documentation
    options.IncludeXmlComments = true;     // default: true
    
    // Contact Info
    options.ContactName = "Dev Team";
    options.ContactEmail = "dev@example.com";
    options.ContactUrl = "https://example.com";
    
    // License
    options.LicenseName = "MIT";
    options.LicenseUrl = "https://opensource.org/licenses/MIT";
});

All Options

Option	Type	Default	Description
Title	string	"Gryd.IO API"	API documentation title
Version	string	"v1"	API version
Description	string?	null	API description
IncludeAuthentication	bool	true	Enable Bearer JWT security scheme
PersistAuthorization	bool	true	Keep token across page refreshes
AutoCaptureToken	bool	true	Auto-capture token from login
LoginEndpointPath	string	"auth/login"	Login endpoint path
TokenJsonPath	string	"data.token"	JSON path to token in response
IncludeXmlComments	bool	true	Include XML doc comments
ContactName	string?	null	Contact name
ContactEmail	string?	null	Contact email
ContactUrl	string?	null	Contact URL
LicenseName	string?	null	License name
LicenseUrl	string?	null	License URL

Per-Endpoint Security (AuthorizeOperationFilter)

GrydSwagger replaces the global AddSecurityRequirement with an IOperationFilter that inspects each endpoint individually.

Behavior

Attribute	Lock Icon	401/403 Response
[Authorize]	✅ Yes	✅ Added
[Authorize(Roles = "Admin")]	✅ Yes	✅ Added
[AllowAnonymous]	❌ No	❌ Not added
No attribute	❌ No	❌ Not added

Before vs After

Before (global security):

// ❌ All endpoints show lock icon, even login
c.AddSecurityRequirement(new OpenApiSecurityRequirement { ... });

After (per-endpoint):

// ✅ Only [Authorize] endpoints show lock
builder.Services.AddGrydSwagger(); // Uses AuthorizeOperationFilter internally

Example

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]                    // ❌ No lock — accessible by anyone
    public IActionResult List() => Ok();

    [Authorize]
    [HttpPost]                   // 🔒 Lock icon — requires Bearer token
    public IActionResult Create() => Ok();

    [Authorize(Roles = "Admin")]
    [HttpDelete("{id}")]         // 🔒 Lock icon — requires Bearer token
    public IActionResult Delete(Guid id) => Ok();
}

Custom Token Path

If your login response has a different structure, configure TokenJsonPath:

// Response: { "result": { "accessToken": "eyJ..." } }
builder.Services.AddGrydSwagger(options =>
{
    options.TokenJsonPath = "result.accessToken";
});

// Response: { "token": "eyJ..." }
builder.Services.AddGrydSwagger(options =>
{
    options.TokenJsonPath = "token";
});

Without Authentication

For APIs that don't use authentication:

builder.Services.AddGrydSwagger(options =>
{
    options.IncludeAuthentication = false;
    options.Title = "Public API";
});

Architecture

Files

File	Description
GrydSwaggerOptions	Configuration POCO with all options
AuthorizeOperationFilter	IOperationFilter for per-endpoint Bearer security
GrydSwaggerExtensions	AddGrydSwagger() / UseGrydSwagger() extension methods

Extension Methods

Method	Target	Description
AddGrydSwagger()	IServiceCollection	Registers Swagger services + Bearer scheme
AddGrydSwagger(Action<GrydSwaggerOptions>)	IServiceCollection	Same with custom options
UseGrydSwagger()	IApplicationBuilder	Configures Swagger UI middleware
UseGrydSwagger(IHostEnvironment)	IApplicationBuilder	Same, only in Development