Overview
This repository extends Swashbuckle for ASP.NET Core services that need more than a one-off AddSwaggerGen setup. It packages reusable registration, XML-comment discovery, common OpenAPI security metadata, and optional Model Context Protocol documentation into focused extensions that can be composed in the same host. The result is a Swagger document that stays aligned with runtime conventions instead of depending on scattered startup code.
Concepts
The packages here build on one idea: keep OpenAPI generation close to the actual service configuration, then layer extra protocol-specific documentation only when the host really exposes that protocol.
Centralized Swagger registration
The core Codebelt.Extensions.Swashbuckle.AspNetCore package treats Swagger setup as an application contract instead of a loose collection of callbacks. AddRestfulSwagger(IServiceCollection, Action<RestfulSwaggerOptions>?) groups OpenApiInfo, XML documentation sources, filter descriptors, and security definitions into RestfulSwaggerOptions, then registers the package-owned option configurators that push those settings into Swashbuckle. That boundary matters when multiple services need the same Swagger defaults, because the registration surface stays in DI and can be inspected or reused instead of being rebuilt around raw SwaggerGenOptions.
Documentation sources as part of the contract
Swagger output in this repository is not limited to endpoint discovery. Codebelt.Extensions.Swashbuckle.AspNetCore includes helpers such as AddFromBaseDirectory, AddByType, AddByAssembly, and AddFromReferencePacks so XML comments from application assemblies and installed framework packs become part of the generated OpenAPI document. The same package also exposes targeted metadata helpers like AddUserAgent, AddJwtBearerSecurity, AddBasicAuthenticationSecurity, and AddXApiKeySecurity, which let a service declare repeated headers and authentication schemes as reusable Swagger configuration instead of hand-editing document filters per application.
Protocol-specific OpenAPI layers
The repository separates general Swagger plumbing from protocol-specific document shape. Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol builds on the base Swashbuckle integration by registering AddMcpServer and McpDocumentFilter, which add MCP transport routes, JSON-RPC request and response schemas, and optional legacy SSE endpoints to the generated document. That split keeps REST-oriented Swagger registration in the smaller base package while letting MCP-enabled hosts opt into the extra route and payload model only when they actually expose /mcp style endpoints.
Usage guidance
Start with Codebelt.Extensions.Swashbuckle.AspNetCore when the goal is to standardize Swagger registration, XML-comment discovery, or common security metadata across an ASP.NET Core API. Add Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol only when the same host needs its OpenAPI document to describe MCP transport behavior and JSON-RPC payloads.
Avoid pulling in the MCP layer just because the service already uses Swagger. The package boundary is deliberate: the base package covers general OpenAPI registration concerns, while the MCP package adds a second protocol model with extra paths and schemas that are only useful for MCP-enabled applications.