ServiceStack/src/ServiceStack.OpenApi.Microsoft/README.md
ServiceStack integration for Microsoft.AspNetCore.OpenApi - the native OpenAPI document generation library in ASP.NET Core.
This package enables ServiceStack services to be documented using Microsoft's built-in OpenAPI support, providing seamless integration with modern OpenAPI UI tools like Scalar, Swagger UI, and others.
Microsoft.AspNetCore.OpenApi (ASP.NET Core's built-in OpenAPI support)dotnet add package ServiceStack.AspNetCore.OpenApi.Microsoft
For Scalar UI support:
dotnet add package Scalar.AspNetCore
var builder = WebApplication.CreateBuilder(args);
// Add Microsoft OpenAPI support
builder.Services.AddOpenApi();
// Add ServiceStack OpenAPI integration
builder.Services.AddServiceStackOpenApi();
// Add ServiceStack
builder.Services.AddServiceStack(typeof(MyServices).Assembly);
var app = builder.Build();
// Configure ServiceStack
app.UseServiceStack(new AppHost());
// Map OpenAPI endpoints (in Development)
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}
app.Run();
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
builder.Services.AddServiceStackOpenApi();
builder.Services.AddServiceStack(typeof(MyServices).Assembly);
var app = builder.Build();
app.UseServiceStack(new AppHost());
if (app.Environment.IsDevelopment())
{
// Map OpenAPI document endpoint
app.MapOpenApi();
// Map Scalar UI endpoint
app.MapScalarApiReference();
}
app.Run();
After configuration, the following endpoints are available:
| Endpoint | Description |
|---|---|
/openapi/v1.json | OpenAPI 3.1 document in JSON format (default document) |
/openapi/{documentName}.json | Named OpenAPI documents |
Scalar.AspNetCore)| Endpoint | Description |
|---|---|
/scalar/v1 | Scalar API reference UI for the default document |
/scalar/{documentName} | Scalar UI for named documents |
Swashbuckle.AspNetCore)| Endpoint | Description |
|---|---|
/swagger/v1/swagger.json | Swagger document endpoint |
/swagger | Swagger UI |
You can configure multiple OpenAPI documents for different API versions or groups:
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// Configure ServiceStack for each document
builder.Services.AddServiceStackOpenApi("v1");
builder.Services.AddServiceStackOpenApi("v2");
builder.Services.AddServiceStackOpenApi(documentName: "v1", configure: metadata =>
{
// Configure metadata
metadata.Title = "My API";
metadata.Version = "1.0.0";
metadata.Description = "My ServiceStack API";
// Add security definitions
metadata.AddBasicAuth();
metadata.AddApiKeyAuth();
metadata.AddBearerAuth();
});
Add authentication schemes to your OpenAPI document:
builder.Services.AddServiceStackOpenApi(configure: metadata =>
{
// Basic Authentication
metadata.AddBasicAuth();
// API Key Authentication
metadata.AddApiKeyAuth();
// Bearer Token Authentication
metadata.AddBearerAuth();
});
Scalar provides a modern, interactive API documentation interface.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference();
}
app.MapScalarApiReference(options =>
{
options
.WithTitle("My API Documentation")
.WithTheme(ScalarTheme.Purple)
.WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
});
See the ServiceStack/tests/OpenApiScalar project for a complete working example.
This package uses Microsoft.AspNetCore.OpenApi instead of Swashbuckle.AspNetCore:
| Feature | Swashbuckle | Microsoft.AspNetCore.OpenApi |
|---|---|---|
| OpenAPI Version | 3.0 | 3.1 |
| Integration | Third-party | Native ASP.NET Core |
| Performance | Good | Better (native) |
| Document Filters | IDocumentFilter | IOpenApiDocumentTransformer |
| Schema Filters | ISchemaFilter | IOpenApiSchemaTransformer |
Make sure you call AddServiceStackOpenApi() with the correct document name that matches your AddOpenApi() call:
// These must match
builder.Services.AddOpenApi("v1");
builder.Services.AddServiceStackOpenApi("v1");
Ensure UseServiceStack() is called before MapOpenApi():
app.UseServiceStack(new AppHost()); // Must be before MapOpenApi
app.MapOpenApi();
See the main ServiceStack license.