amafjarkasi/specforge-openapi-sdk-codegen

Forge production-ready client SDKs from OpenAPI 3.x specs.
One language-neutral IR. Emitters for TypeScript, Go, Rust, and WASM.
With runtime validation, documentation generation, and a plugin system.

## Why specforge? Most OpenAPI generators have critical shortcomings that leave teams building runtime infrastructure by hand: | Problem with other generators | specforge’s answer | |---|---| | **Incomplete types** — nullable, oneOf, allOf produce broken or `any`-typed output | Full composition support: allOf property merging, oneOf type guards, discriminator mapping, nullable propagation | | **No runtime** — you get types but no client, auth, retry, or error handling | Production-ready runtime: auth providers, exponential backoff, pagination helpers, concurrency control, middleware, idempotency keys, SSE streaming | | **Single language** — each generator is a silo with different behavior | One IR, four targets: TypeScript, Go, Rust, and WASM plugins share the same resolved spec | | **No validation** — generated code trusts the server blindly | Runtime request/response validation catches contract violations in dev and tests | | **No testing** — you write mock servers by hand | `specforge test` generates mock server tests from example responses | | **No documentation** — separate tools for API docs | `specforge docs` generates a static HTML documentation site | | **No CI integration** — manual diffing and linting | `specforge diff` detects breaking changes, `specforge check` lints specs, GitHub Action for one-line CI | ### The specforge advantage **1. Parse once, emit many** Your OpenAPI spec is parsed and resolved into a language-neutral IR (Intermediate Representation). Every emitter — TypeScript, Go, Rust, or a custom WASM plugin — walks the same IR. This means: - Consistent behavior across languages (same retry logic, same pagination, same auth) - Adding a new language means writing one emitter, not re-implementing the parser - The IR is a documented, versioned JSON schema (`assets/ir-schema.json`) **2. SDKs that actually work in production** specforge doesn’t just generate types — it generates **complete client libraries** with: - **Auth** — Bearer tokens (static or dynamic), API keys, custom providers - **Retry** — Full-jitter exponential backoff with configurable max retries and per-attempt timeouts - **Pagination** — Cursor and offset pagination helpers that walk all pages automatically - **Concurrency** — Async semaphore to limit in-flight requests (`maxConcurrent`) - **Deduplication** — In-flight request coalescing for GET/HEAD/OPTIONS (one upstream call, N waiters) - **Middleware** — Composable request/response middleware chain (logging, tracing, header injection) - **Idempotency** — Automatic `Idempotency-Key` headers on POST/PUT/PATCH/DELETE - **Streaming** — SSE and chunk streaming helpers with proper error handling - **Validation** — Runtime request/response body validation against the spec **3. Multi-language with one source of truth** Generate SDKs for all your teams from the same spec: graph LR A[“📄 OpenAPI 3.x
YAML / JSON”] --> B[“⚙️ specforge-core
parse · resolve
language-neutral IR”] B --> C[“🔧 emitters
TS · Go · Rust · WASM
typed client + runtime”] style A fill:#1a0f0a,stroke:#f97316,color:#fef3c7 style B fill:#1a0f0a,stroke:#ef4444,color:#fef3c7 style C fill:#1a0f0a,stroke:#fbbf24,color:#fef3c7 Each generated SDK is a standalone project — no shared runtime dependency, no version coupling. The TypeScript SDK is a dual ESM/CJS package, the Go SDK uses only stdlib, and the Rust SDK uses `reqwest` + `serde`. **4. Built for CI** - `specforge check` lints your spec with configurable rules (`.specforge.yaml`) - `specforge diff` detects breaking changes between two spec versions — exit code 1 on breaking changes - GitHub Action for one-line CI integration - Deterministic output for reproducible builds and effective caching **5. Full IDE integration** The [VS Code extension](vscode-extension/) provides 23 commands, auto-validation on save, context menus, keyboard shortcuts, and a status bar — everything you need to work with OpenAPI specs without leaving your editor. **6. Extensible via WASM plugins** Need Kotlin? Swift? Python? Build a custom emitter as a WASM plugin: use specforge_plugin::{Plugin, PluginResult, GeneratedFile}; struct MyPlugin; impl Plugin for MyPlugin { fn generate(&self, ir_json: &str) -> PluginResult { // Parse the IR, emit files for your language } } specforge_plugin::export_plugin!(MyPlugin); The plugin receives the full IR as JSON and returns generated files. Compile to WASM and run with `specforge`. ## Features ### Spec parsing & resolution | Feature | Benefit | |---|---| | **OpenAPI 3.0 + 3.1** | Handles both spec versions transparently. 3.1 `type` arrays, `$ref` siblings, and numeric `exclusiveMinimum` are auto-converted to 3.0 for parsing. | | **Full `$ref` resolution** | Named types stay named — no exponential inlining blow-ups. Self-referential and mutual `$ref` cycles are safe by construction. | | **Composition support** | `allOf` merges properties (last-wins, required union). `oneOf`/`anyOf` generate type guards. Discriminator mapping preserved. | | **AllOf type aliases** | When allOf has one `$ref` member, Go emits embedded structs and Rust emits `#[serde(flatten)]` — proper composition, not flat merging. | | **Deterministic output** | `IndexMap` preserves spec order. Same spec + same version = identical output. Bit-stable for caching and diffing. | | **Spec linting** | 8 configurable rules (duplicate operation IDs, missing descriptions, unused schemas, etc.) with `.specforge.yaml` config. | | **Breaking change detection** | `specforge diff` compares two specs: removed operations, new required parameters, type changes. Exit code 1 for CI gates. | ### Generated SDK runtimes Every generated SDK is a **complete, production-ready client** — not just types. | Capability | What it does | Why it matters | |---|---|---| | **Typed models + operations** | Full request/response types with proper optionality | Catch type errors at compile time, not in production | | **Auth providers** | Bearer (static/dynamic), API key (header/query), custom | Swap credentials without touching client code | | **Retry + backoff** | Full-jitter exponential backoff, configurable max retries | Handle transient failures gracefully without thundering herd | | **Per-attempt timeouts** | Configurable timeout on each retry attempt | Prevent hung requests from blocking your app | | **Pagination helpers** | Cursor and offset pagination that walks all pages | One call instead of manual loop + cursor management | | **Concurrency semaphore** | `maxConcurrent` limits in-flight requests | Prevent overwhelming the API or hitting rate limits | | **In-flight dedupe** | Coalesces identical GET/HEAD/OPTIONS requests | N concurrent callers → 1 upstream call, N shared results | | **Middleware chain** | Composable request/response middleware | Add logging, tracing, header injection without modifying the client | | **Idempotency keys** | Auto-generated `Idempotency-Key` on unsafe methods | Safe retries on POST/PUT/PATCH/DELETE without duplicate side effects | | **SSE streaming** | Server-Sent Event parser with proper error handling | Real-time data streams without manual parsing | | **Runtime validation** | Validate request/response bodies against the spec | Catch API contract violations in dev and tests, not production | | **oneOf type guards** | `isPetCreated()`, `narrowPetEvent()` (TS); `is_pet_created()`, `discriminant()` (Rust) | Safely narrow union types at runtime | | **Response caching** | ETag-based caching with TTL expiry and 304 handling | Avoid re-fetching unchanged data | | **Rate limiting** | Token bucket and sliding window rate limiters | Prevent overwhelming APIs | | **Logging** | Pluggable `Logger` interface (ConsoleLogger, NoopLogger) | Structured request/response logging | | **Telemetry** | Request metrics, error tracking, cache hit/miss | Monitor SDK performance | | **i18n** | Localized error messages (8 locales) | International error handling | | **Interceptors** | Request/response body transformers | Post-process data without middleware | | **Dependency injection** | `ServiceContainer` for all 3 SDKs (HTTP client, cache, rate limiter, logger, telemetry) | Test with mock HTTP clients | | **Validation middleware** | Auto-validate all requests/responses against the spec | Catch contract violations without manual validation | ### Language-specific highlights **TypeScript** - Dual ESM/CJS package (`sideEffects: false` for tree-shaking) - Native `fetch` — no runtime dependencies - Discriminated union error types (`ApiError`) - `isX()` / `narrowX()` type guards for oneOf unions - Per-model `validatePet()` functions - Response caching with ETags - Token bucket / sliding window rate limiting - `Logger` interface with ConsoleLogger - `RequestInterceptor` / `ResponseInterceptor` / `ResponseTransformer` - `@param`, `@returns`, `@throws` JSDoc on generated functions **Go** - Stdlib only (`net/http`, `encoding/json`) — zero third-party dependencies - Embedded structs for allOf composition - `New{Union}(m map[string]any)` for discriminated oneOf deserialization - `New{Union}FromJSON(raw json.RawMessage)` for non-discriminated unions - `WithValidation(true)` for runtime request/response checking - `WithCache(ttl)`, `WithRateLimiter(limiter)`, `WithLogger(logger)` - `WithRequestInterceptors()` / `WithResponseInterceptors()` / `WithResponseTransformers()` **Rust** - `reqwest` + `serde` + `tokio` async runtime - `#[serde(flatten)]` for allOf composition - `impl PetEvent { fn discriminant() -> &str; fn is_pet_created() -> bool; }` for oneOf - `SseStream` for SSE parsing over `bytes_stream()` - `.validation(true)`, `.cache_ttl(Duration)`, `.rate_limiter(limiter)`, `.logger(logger)` - `.http_client(reqwest::Client)` for DI in tests - `RequestInterceptor` / `ResponseInterceptor` / `ResponseTransformer` traits **WASM plugins** - `specforge-plugin` crate with `Plugin` trait and `export_plugin!` macro - Receives full IR as JSON, returns generated files - Compile to `wasm32-wasi` for any language emitter ### CLI subcommands (22 commands) | Command | What it does | |---|---| | `specforge generate` | Generate an SDK from an OpenAPI spec | | `specforge check` | Lint and validate a spec with configurable rules | | `specforge diff` | Compare two specs — markdown/JSON/color output, inline schema diffs | | `specforge emit` | Dump the resolved IR as JSON (for external tools / plugins) | | `specforge init` | Scaffold a new OpenAPI spec with a `/health` endpoint | | `specforge convert` | Convert between OpenAPI 3.0 and 3.1 | | `specforge merge` | Merge multiple spec files into one | | `specforge migrate` | Generate a migration guide between two spec versions | | `specforge docs` | Generate a static HTML API documentation site | | `specforge test` | Generate mock server tests from spec examples | | `specforge versions` | List API versions in a spec directory | | `specforge workspace` | Generate SDKs for all specs in a workspace config | | `specforge workspace-init` | Generate a workspace config from a directory | | `specforge dashboard` | Generate HTML metrics dashboard from SDK telemetry | | `specforge security` | Analyze auth requirements and detect issues | | `specforge graph` | Generate schema dependency diagrams (Mermaid/DOT) | | `specforge analyze` | Detect unused schemas, duplicates, optimization opportunities | | `specforge mock` | Start a local mock server from spec examples | | `specforge export` | Export Swagger Editor-compatible spec (inline `$ref`) | | `specforge demo` | Generate a realistic demo Petstore spec | | `specforge evolution` | Track schema changes over git commits | | `specforge infer` | Generate an OpenAPI spec from sample JSON | | `specforge verify` | Validate a running API against the spec | | `specforge market` | Browse/search/manage specs in the marketplace | | `specforge market search` | Search specs by name, description, or tags | | `specforge market list` | List all curated specs with ratings | | `specforge market info` | Get detailed spec information | | `specforge market add` | Add a spec to the marketplace | | `specforge changelog` | Auto-generate CHANGELOG from spec changes | ### Quality gates - **227 unit tests** across core, emitters, and CLI - **21 test fixtures** (0.02MB to 14MB): petstore, GitHub, Stripe, Kubernetes, Atlassian, OpenAI, Vercel, Linode, Bitbucket, Adyen, Notion, Spotify, Adobe AEM, CircleCI, Okta, and more - **Compile gates**: generated Go must `go build`, generated Rust must `cargo check` - **E2E smoke**: mock server × list/show/create + auth/retry/pagination (all 3 langs) - **E2E advanced**: concurrency serialisation, dedupe single-flight, middleware rewrite, idempotency-key on POST, SSE parse (all 3 langs) - **Performance benchmarks**: criterion benchmarks + 13 perf tests (petstore < 100ms, GitHub/Stripe < 10s) - **Multi-platform CI**: Linux, macOS, Windows (GitHub Actions matrix) - **Cross-compiled releases**: 5 targets (linux amd64/arm64, macOS Intel/Apple Silicon, Windows) - **Production hardening**: thread safety audit, unwrap/expect audit, SDK integration tests, stability enforcement ### VS Code Extension The [specforge VS Code extension](vscode-extension/) provides a complete IDE experience for OpenAPI development: | Feature | What it does | |---------|--------------| | **Generate SDK** | Pick language (TS/Go/Rust), generate to output directory | | **Check Spec** | Validate spec with `--strict` mode | | **Diff Spec** | Compare two spec versions side-by-side | | **Preview IR** | View resolved intermediate representation as JSON | | **Analyze Spec** | Find unused schemas, duplicates, optimization opportunities | | **Security Analysis** | Audit auth requirements across all operations | | **Show Dependency Graph** | Mermaid visualization of schema relationships | | **Generate Docs** | Static HTML documentation site | | **Generate Tests** | Mock server tests from spec examples | | **Merge Specs** | Combine multiple spec files into one | | **Migrate** | Generate migration guide between spec versions | | **Mock Server** | Start local mock server from spec examples | | **Export** | Swagger Editor compatible output | | **Infer** | Generate OpenAPI spec from sample JSON | | **Verify** | Validate running API against spec | | **Evolution** | Track schema changes over git commits | **IDE integration:** - Auto-validate specs on save (configurable) - Context menus (right-click YAML/JSON files) - Keyboard shortcuts (`Ctrl+Shift+G` generate, `Ctrl+Shift+V` check) - Status bar with mock server indicator - Output channel for all CLI output - Progress notifications for long operations - Interactive pickers for language, format, and version **Quick start:** 1. Install the extension from the `vscode-extension/` directory 2. Open a folder containing an OpenAPI spec 3. Press `Ctrl+Shift+G` to generate an SDK ## Quick start ### 1. Build the CLI cargo build -p specforge-cli # → target/debug/specforge ### 2. Generate an SDK # TypeScript (default) — native fetch, dual ESM/CJS package ./target/debug/specforge generate openapi.yaml -o ./sdk-ts -l ts # Go — stdlib net/http only ./target/debug/specforge generate openapi.yaml -o ./sdk-go -l go \ -n github.com/acme/widget-go # Rust — reqwest + serde ./target/debug/specforge generate openapi.yaml -o ./sdk-rs -l rust \ -n widget_sdk # Lint a spec without generating ./target/debug/specforge check openapi.yaml ./target/debug/specforge check openapi.yaml --strict ### 3. Call your API

TypeScript

import { createClient, bearerAuth, streamSse } from "./sdk-ts/src/index.ts"; const client = createClient({ baseUrl: "https://api.example.com", auth: bearerAuth(() => process.env.API_TOKEN!), maxConcurrent: 8, dedupe: true, idempotency: true, retry: { maxRetries: 3 }, }); const page = await client.pets.listPets({ limit: 20 }); // Streaming (SSE) const res = await client.request("GET", "/events"); for await (const ev of streamSse(res)) { console.log(ev.event, ev.data); }

Go

c := sdk.NewClient(). WithBaseURL("https://api.example.com"). WithBearerToken(os.Getenv("API_TOKEN")). WithTimeout(10 * time.Second). WithMaxConcurrent(8). WithDedupe(true). WithIdempotency(true). WithRetry(sdk.DefaultRetryOptions()) c.Use(func(ctx context.Context, req *sdk.MiddlewareRequest, next func(context.Context, *sdk.MiddlewareRequest) (*sdk.MiddlewareResponse, error)) (*sdk.MiddlewareResponse, error) { start := time.Now() res, err := next(ctx, req) log.Printf("%s %s %v", req.Method, req.URL, time.Since(start)) return res, err }) pets, err := c.ListPets(ctx, 20) // Streaming SSE res, err := c.DoStream(ctx, "GET", "/events", nil, nil) defer sdk.DrainAndClose(res) it := sdk.NewSseIterator(res) for it.Next() { ev := it.Event() fmt.Println(ev.Event, ev.Data) }

Rust

use std::time::Duration; use widget_sdk::{api, Client}; use widget_sdk::streaming::SseStream; let client = Client::builder() .base_url("https://api.example.com") .bearer_token(std::env::var("API_TOKEN")?) .timeout(Duration::from_secs(10)) .max_concurrent(8) .dedupe(true) .idempotency(true) .build()?; let pets = api::list_pets(&client, Some(20)).await?; // Streaming SSE let res = client.request_stream(reqwest::Method::GET, "/events", &[], None).await?; let mut sse = SseStream::new(res.bytes_stream()); while let Some(ev) = sse.next_event().await? { println!("{}: {}", ev.event, ev.data); }

## CLI reference specforge Commands: generate Generate an SDK from an OpenAPI spec check Lint and validate an OpenAPI spec without generating diff Compare two OpenAPI specs and report breaking changes emit Emit the resolved IR as JSON (for external emitters / plugins) init Scaffold a new minimal OpenAPI spec convert Convert between OpenAPI 3.0 and 3.1 merge Merge multiple OpenAPI spec files into one migrate Generate a migration guide between two spec versions docs Generate static HTML API documentation test Generate mock server tests for generated SDKs versions List API versions in a spec directory workspace Generate SDKs for all specs in a workspace config workspace-init Generate a workspace config from a directory help Print this message or the help of the given subcommand ### `specforge generate` specforge generate [OPTIONS] Arguments: Path to OpenAPI YAML or JSON Options: -o, --out Output directory [default: ./generated] -l, --lang ts | go | rust [default: ts] -n, --name Package / module / crate name override --version API version (when spec is a directory) --profile Output timing breakdown for each pipeline stage -v, --log-level error|warn|info|debug|trace [default: info] -h, --help -V, --version | Language | `-n` means | Default if omitted | |----------|------------|--------------------| | **ts** | npm package name in `package.json` | `@sdk` | | **go** | Go module path in `go.mod` | `github.com/example/