CoreSystem.OpenApi.Swashbuckle
1.2.1
dotnet add package CoreSystem.OpenApi.Swashbuckle --version 1.2.1
NuGet\Install-Package CoreSystem.OpenApi.Swashbuckle -Version 1.2.1
<PackageReference Include="CoreSystem.OpenApi.Swashbuckle" Version="1.2.1" />
<PackageVersion Include="CoreSystem.OpenApi.Swashbuckle" Version="1.2.1" />
<PackageReference Include="CoreSystem.OpenApi.Swashbuckle" />
paket add CoreSystem.OpenApi.Swashbuckle --version 1.2.1
#r "nuget: CoreSystem.OpenApi.Swashbuckle, 1.2.1"
#:package CoreSystem.OpenApi.Swashbuckle@1.2.1
#addin nuget:?package=CoreSystem.OpenApi.Swashbuckle&version=1.2.1
#tool nuget:?package=CoreSystem.OpenApi.Swashbuckle&version=1.2.1
⚡ CoreSystem.OpenApi.Swashbuckle
Generate the OpenAPI document once. Reuse the conventions everywhere.
CoreSystem.OpenApi.Swashbuckle provides the OpenAPI and Swagger infrastructure shared by CoreSystem-based APIs on .NET 8, .NET 9 and .NET 10. It owns the document wiring, the response attributes and the filters, while each application keeps its own title, servers, examples and error vocabulary.
✨ Features
- ✅ One-call Swagger generation wiring (
AddCoreOpenApi) and hosting (UseCoreOpenApi) - ✅ Bearer security scheme applied to every operation
- ✅
ProducesOkAttribute<T>,ProducesCreatedAttribute<T>andProducesNoContentAttributeresponse attributes - ✅
Locationheader documented on every201 Createdresponse - ✅ Redundant
text/plainandtext/jsonrepresentations removed - ✅ Shared problem-details responses declared once as
$refcomponents - ✅ Configurable error codes, type URIs, examples and schemas
- ✅ Patched document cached in memory instead of rebuilt per request
- ✅ Invalid JSON is returned unchanged, so the patcher is safe to compose
📦 Installation
dotnet add package CoreSystem.OpenApi.Swashbuckle
🚀 Quick Start
Register the document and map the endpoint:
using Core.OpenApi.Swashbuckle.DependencyInjection;
using Core.OpenApi.Swashbuckle.Extensions;
using Core.OpenApi.Options;
using Core.OpenApi.Attributes;
builder.Services.AddCoreOpenApi(options =>
{
options.Title = "Orders API";
options.Description = "Order management endpoints";
options.Servers.Add(new OpenApiServerDescriptor
{
Url = "https://api.example.com",
Description = "Production"
});
});
var app = builder.Build();
app.UseCoreOpenApi();
The application now serves:
| Route | Content |
|---|---|
/swagger/v1/swagger.json |
The patched document |
/swagger |
Swagger UI |
swagger-original/v1/swagger.json |
The unpatched generator output |
Annotate controllers with the response attributes:
using Core.OpenApi.Attributes;
[HttpPost]
[ProducesCreatedAttribute<OrderResponse>]
public async Task<IActionResult> Create(CreateOrderRequest request)
⚙️ Problem Responses
Every configured error response is declared once in components.responses and
referenced from the operations that already document the status code:
builder.Services.AddCoreOpenApi(options =>
{
options.ProblemResponses.SchemaId = "AppProblemDetails";
options.ProblemResponses.TypePrefix = "urn:orders:error:";
options.ProblemResponses.TraceIdExample =
"00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01";
// Rate limiting is applied to every endpoint, so document 429 everywhere.
options.ProblemResponses.Definitions
.Single(definition => definition.StatusCode == "429")
.IncludeWhenMissing = true;
});
IncludeWhenMissing is false by default, so a status code is only added to
operations that already declare it. Set it to true only when the corresponding
middleware really applies to the whole API.
An existing 400 response is replaced only when it already looks like a problem
response (application/problem+json, or a schema reference to one of the
configured problem schemas). That keeps a custom validation payload untouched.
🔌 Extending the Generator
Features that live in other packages stay out of this one. Use the callback:
using Swashbuckle.AspNetCore.Annotations;
using Swashbuckle.AspNetCore.Filters;
builder.Services.AddCoreOpenApi(options =>
{
options.ConfigureSwaggerGen = gen =>
{
gen.EnableAnnotations();
gen.ExampleFilters();
};
});
The same pattern applies to the JSON endpoint, for example to keep it out of the rate limiter and out of the document:
builder.Services.AddCoreOpenApi(options =>
{
options.ConfigureJsonEndpoint = endpoint => endpoint
.DisableRateLimiting()
.ExcludeFromDescription();
});
🧩 Public API
| Type | Description |
|---|---|
AddCoreOpenApi() |
Registers Swagger generation, the filters and the options. |
UseCoreOpenApi() |
Maps the patched document endpoint and configures Swagger UI. |
CoreOpenApiOptions |
Title, servers, security, XML comments and callbacks. |
OpenApiProblemResponsesOptions |
The shared problem response catalog. |
ProblemResponseDefinition |
One response: status code, component, error code and example. |
OpenApiDocumentPatcher |
Applies the catalog to a serialized document. |
JsonOnlyResponsesOperationFilter |
Removes redundant text media types. |
CreatedWithLocationDocumentFilter |
Documents the Location header on 201. |
ProducesOkAttribute<T> / ProducesCreatedAttribute<T> / ProducesNoContentAttribute |
Response attributes. |
🏗 Architecture
┌──────────────────────────────────────┐
│ Your ASP.NET Core application │
└──────────────┬───────────────────────┘
│ AddCoreOpenApi / UseCoreOpenApi
▼
┌──────────────────────────────────────┐
│ Core.OpenApi.Swashbuckle │
│ (SwaggerGen filters, document │
│ patcher, Swagger UI wiring) │
└──────────────┬───────────────────────┘
│ depends on
▼
┌──────────────────────────────────────┐
│ Core.OpenApi │
│ (contracts, options, attributes) │
└──────────────────────────────────────┘
The provider builds on top of the dependency-free Core.OpenApi contracts:
it registers Swagger generation, applies the shared filters and maps the patched
document endpoint, while the base package keeps the options and attributes.
📖 Documentation
- Getting Started
- Configuration
- Problem Responses
🤝 Contributing
Issues, discussions and pull requests are welcome.
📄 License
Released under the MIT License.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- CoreSystem.OpenApi (>= 1.2.1)
- Microsoft.OpenApi (>= 1.6.25)
- Swashbuckle.AspNetCore.SwaggerGen (>= 9.0.6)
- Swashbuckle.AspNetCore.SwaggerUI (>= 10.3.1)
-
net8.0
- CoreSystem.OpenApi (>= 1.2.1)
- Microsoft.OpenApi (>= 1.6.25)
- Swashbuckle.AspNetCore.SwaggerGen (>= 9.0.6)
- Swashbuckle.AspNetCore.SwaggerUI (>= 10.3.1)
-
net9.0
- CoreSystem.OpenApi (>= 1.2.1)
- Microsoft.OpenApi (>= 1.6.25)
- Swashbuckle.AspNetCore.SwaggerGen (>= 9.0.6)
- Swashbuckle.AspNetCore.SwaggerUI (>= 10.3.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
1.2.1: Fixed Development server discovery. Wildcard listen addresses (+, *, 0.0.0.0, [::])
from ASPNETCORE_URLS are no longer added as Local servers, so the generated document only
lists URLs that clients can call. Patch release. Requires CoreSystem.OpenApi 2.2.0, which
changes the default problem schema names (see its release notes).
1.2.0: Added ProducesConflictProblemAttribute (HTTP 409) for documenting conflict
problem responses. Minor version bump.