GM.Documentation 1.3.0

<p align="center"> <img src="https://raw.githubusercontent.com/gmetskhvarishvili/GM.Documentation/master/icon.png" alt="GM.Documentation" width="140" height="140" /> </p>

GM.Documentation

A lightweight, configuration-driven Swagger/OpenAPI setup for ASP.NET Core. Two calls give you a fully configured Swagger UI — API versioning, FluentValidation rules in the schema, OAuth2 security, required-header parameters, custom date formatting, and custom CSS/JS — all driven from configuration. Part of the GM.* family of packages. Targets net10.0.

It builds on Swashbuckle, Asp.Versioning, and MicroElements.Swashbuckle.FluentValidation.

Install

dotnet add package GM.Documentation

Register

using GM.Documentation;

builder.Services.AddGMDocumentation(builder.Configuration, "Swagger");

Use

var app = builder.Build();

app.UseGMDocumentation();

That serves the UI at the app root (/), wires one Swagger document per discovered API version, and injects Assets/swagger.css + Assets/swagger.js if present.

Configure

Everything comes from the configuration section you name (shape matches SwaggerDocOptions); every value is optional and falls back to a sensible default:

{
  "Swagger": {
    "Enabled": true,
    "Title": "My API",
    "Description": "My API description",
    "DateTimeFormat": "dd/MM/yyyy HH:mm",
    "Headers": [ "X-Tenant-Id" ],
    "Contact": { "Name": "Team", "Email": "team@example.com", "Url": "https://example.com" },
    "License": { "Name": "MIT", "Url": "https://opensource.org/licenses/MIT" },
    "Authorization": {
      "Scheme": "oauth2",
      "Name": "Authorization",
      "Authority": "https://identity.example.com",
      "TokenEndpoint": "https://identity.example.com/connect/token",
      "RequiredScopes": "api openid profile",
      "Flows": [ "authorizationCode", "clientCredentials" ],
      "ClientName": "swagger",
      "ClientSecret": "secret"
    }
  }
}

You can also override options in code — values passed here win over configuration:

builder.Services.AddGMDocumentation(builder.Configuration, "Swagger", new SwaggerDocOptions
{
    Title = "Overridden Title"
});

What you get

• API versioning — one Swagger document per IApiVersionDescriptionProvider group (falls back to v1).
• FluentValidation in the schema — validators are reflected into the OpenAPI schema.
• OAuth2 security — authorization code, client credentials, password, and implicit flows from config.
• Required headers — headers listed in config are added to every operation.
• Custom date formatting — DateTime/DateTime? render with your configured format.
• Custom UI assets — Assets/swagger.css and Assets/swagger.js are injected when present.
• XML comments — every *.xml doc file next to the app is included automatically.

Contributing & releases

Versioning is automated from Conventional Commits — see CONTRIBUTING.md.

License

MIT — see LICENSE.