CoreSystem.OpenApi.Swashbuckle
1.0.0
See the version list below for details.
dotnet add package CoreSystem.OpenApi.Swashbuckle --version 1.0.0
NuGet\Install-Package CoreSystem.OpenApi.Swashbuckle -Version 1.0.0
<PackageReference Include="CoreSystem.OpenApi.Swashbuckle" Version="1.0.0" />
<PackageVersion Include="CoreSystem.OpenApi.Swashbuckle" Version="1.0.0" />
<PackageReference Include="CoreSystem.OpenApi.Swashbuckle" />
paket add CoreSystem.OpenApi.Swashbuckle --version 1.0.0
#r "nuget: CoreSystem.OpenApi.Swashbuckle, 1.0.0"
#:package CoreSystem.OpenApi.Swashbuckle@1.0.0
#addin nuget:?package=CoreSystem.OpenApi.Swashbuckle&version=1.0.0
#tool nuget:?package=CoreSystem.OpenApi.Swashbuckle&version=1.0.0
⚡ 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. |
📖 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 (>= 2.0.0)
- Microsoft.OpenApi (>= 1.6.25)
- Swashbuckle.AspNetCore.SwaggerGen (>= 9.0.6)
- Swashbuckle.AspNetCore.SwaggerUI (>= 9.0.6)
-
net8.0
- CoreSystem.OpenApi (>= 2.0.0)
- Microsoft.OpenApi (>= 1.6.25)
- Swashbuckle.AspNetCore.SwaggerGen (>= 9.0.6)
- Swashbuckle.AspNetCore.SwaggerUI (>= 9.0.6)
-
net9.0
- CoreSystem.OpenApi (>= 2.0.0)
- Microsoft.OpenApi (>= 1.6.25)
- Swashbuckle.AspNetCore.SwaggerGen (>= 9.0.6)
- Swashbuckle.AspNetCore.SwaggerUI (>= 9.0.6)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
1.0.0 Initial release. Swagger generation wiring, response attributes, operation and document
filters, and a configurable OpenAPI document patcher that turns inline error responses
into shared component references.