ApiTestSpark 1.3.0

ApiTestSpark

Embed the API Test Spark React SPA into any .NET 10 Minimal API with a single method call. Autodiscovers your OpenAPI v3 endpoints and renders a full-featured interactive test harness at /api-test-spark/.

Live Demo  ·  GitHub  ·  NuGet

Install

dotnet add package ApiTestSpark

Quickstart

using ApiTestSpark;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();
app.MapOpenApi();          // /openapi/v1.json
app.MapApiTestSpark();     // /api-test-spark/

app.Run();

Navigate to https://localhost:{port}/api-test-spark/ — the harness autodiscovers all your endpoints.

Configuration

All options are optional. Pass an Action<ApiTestSparkOptions> to configure:

app.MapApiTestSpark(options =>
{
    options.OpenApiUrl             = "/openapi/v1.json";        // default: "/openapi.json"
    options.AuthScheme             = "Bearer";                  // pre-populates auth field
    options.DefaultHeaders["X-Tenant-Id"] = "acme";            // injected into every SPA request
    options.Environments           = ["Development", "Staging"]; // empty = all environments
    options.EnableDemoIntegrations = false;                     // hide JokeAPI + JSONPlaceholder
});

Options reference

Features

• OpenAPI autodiscovery — endpoints grouped by tag in a collapsible accordion; real-time search filter
• Remote API Explorer — browse and test a remote REST API from its OpenAPI document via a server-side spec proxy; API key and Bearer token injected server-side so credentials never appear in the browser network tab
• Full metadata surface — descriptions rendered as markdown, response codes as coloured badges with expandable inline schemas, operationId as a copyable chip, schema constraint tables
• JSON scaffold — request body pre-filled from example → default → enum[0] → type placeholder; nested objects and arrays scaffolded recursively
• Response rendering — arrays as sortable tables, objects as editable forms, primitives in pre blocks
• API Doc Builder (/api-docs) — select endpoints, capture live curl + responses, annotate sections, export markdown
• Remote API Doc Builder (/remote-api-docs) — same documentation capture for remote API endpoints
• Header token expansion — {session-guid} and {request-guid} tokens in header values are replaced at request time with real UUIDs
• Debug panel — drag-resizable, captures every request/response/error/metric; cURL snippet per request; FIFO buffered
• Environment gating — one option keeps the harness off production
• Demo integration toggle — set EnableDemoIntegrations = false to hide the built-in JokeAPI and JSONPlaceholder screens; show only your host API and the API Doc Builder
• Zero extra dependencies — 181 KB package, no wwwroot changes, nothing copied to your project

Clean install — your API only

Set EnableDemoIntegrations = false to remove the JokeAPI and JSONPlaceholder demo screens entirely. The home page shows only Host API Explorer and API Doc Builder — no sample data, no external API noise.

app.MapApiTestSpark(options =>
{
    options.OpenApiUrl             = "/openapi/v1.json";
    options.Environments           = ["Development", "Staging"];
    options.EnableDemoIntegrations = false;
});

Remote API Explorer

Point the harness at a remote REST API by configuring RemoteBaseUrl and RemoteOpenApiUrl. The harness fetches the remote spec server-side (credentials stay off the browser network tab) and exposes a full endpoint explorer and doc builder for the remote API.

app.MapApiTestSpark(options =>
{
    options.OpenApiUrl                   = "/openapi/v1.json";
    options.RemoteBaseUrl                = "https://api.example.com";
    options.RemoteOpenApiUrl             = "https://api.example.com/openapi.json";
    options.RemoteOpenApiApiKeyHeader    = "x-api-key";
    options.RemoteOpenApiApiKeyValue     = "your-api-key";
    // Optional: correlation headers with per-request UUID tokens
    options.RemoteDefaultHeaders["correlationId"] = "{request-guid}";
    options.RemoteDefaultHeaders["sessionId"]     = "{session-guid}";
});

Security note: The harness is intended for local and trusted development environments only. Do not expose it to the public internet.

Getting the most out of API Test Spark

API Test Spark reads your OpenAPI v3 document. Every annotation you add to your API is surfaced directly in the harness. The more metadata you provide, the richer the testing experience.

Tag endpoints with "Namespace: Label" format — creates a two-level collapsible accordion:

app.MapGroup("/products").WithTags("Products: Catalog").MapProducts();
app.MapGroup("/orders").WithTags("Orders: Lifecycle").MapOrders();

Name, summarise, and describe every operation — summary is the card title; description renders as markdown:

group.MapGet("/{id}", GetById)
     .WithName("GetProductById")
     .WithSummary("Get a product by ID")
     .WithDescription("Returns a single product. Seeded IDs are **1–10**. Returns **404** if not found.");

Declare every response code — each becomes a coloured badge with an expandable inline schema:

.Produces<Product>(StatusCodes.Status200OK)
.Produces(StatusCodes.Status404NotFound)

Or use TypedResults — it infers response types automatically without extra .Produces() calls.

Annotate your schema types — [Description], [Required], [Range], [MinLength], [MaxLength] all appear as columns in the schema property table:

public record Product(
    [property: Description("Display name.")][property: Required][property: MaxLength(100)]
    string Name,
    [property: Description("Unit price in USD.")][property: Range(0.01, 99999.99)]
    decimal Price
);

Set examples or defaults — the JSON scaffold fills from example → default → enum[0] → type placeholder. Without examples every field shows a generic placeholder; with them testers can fire requests immediately.

Add a workflow walkthrough to info.description — renders as markdown in the API info header; ideal for linking resource groups and describing end-to-end flows.

See the live demo and full best-practices guide for annotated source examples.

Reverse proxy

Call UseForwardedHeaders() before MapApiTestSpark() so the config endpoint reports the correct public base URL:

app.UseForwardedHeaders();
app.MapApiTestSpark();

Local development (Vite dev server)

If your React dev server and .NET API run on different ports, allow the dev origin:

app.MapApiTestSpark(options =>
{
    options.CorsOrigins = ["http://localhost:5151"];
});

Diagnostics

{
  "Logging": {
    "LogLevel": {
      "ApiTestSpark": "Debug"
    }
  }
}

License

MIT — github.com/markhazleton/apitestspark