forge README

The project's README from github.com/cloudflare/forge. As one markdown file: README.md.

Forge

Forge is a schema-first OpenAPI code generation and surface tooling framework. It provides a plugin-based architecture for resolving OpenAPI 3.x specifications, applying JSONPath-based overlays, and generating typed SDKs, CLI interfaces, runtime helpers, and documentation.

Packages

This monorepo contains:

Architecture

Forge separates the API definition from surface implementations:

                  +--------------------------------+
                  |  OpenAPI 3.x Specification     |
                  +---------------+----------------+
                                  |
                                  v
                  +--------------------------------+
                  |  JSONPath Overlays (Optional)  |
                  +---------------+----------------+
                                  |
                                  v
+--------------------------------------------------------------------+
|                         @cloudflare/forge                          |
|                                                                    |
|  - OpenApiResolver: $ref dereferencing, parameter/body extraction   |
|  - Schema model: typed command/method hierarchy                     |
|  - Plugin lifecycle: init -> transform -> finalize                |
+---------------------------------+----------------------------------+
                                  |
            +---------------------+---------------------+
            |                                           |
            v                                           v
+-----------------------+                   +-----------------------+
|  TypeScript SDK       |                   |  Other Surface        |
|  (@cloudflare/forge-  |                   |  Transformers (CLI,   |
|   transformer-sdk-ts) |                   |   docs, runtimes)     |
+-----------------------+                   +-----------------------+

Getting Started

Installation

pnpm add @cloudflare/forge

Basic Usage

import { Forge, init } from '@cloudflare/forge';

// Load any OpenAPI 3.x specification
const spec = {
  openapi: '3.0.0',
  info: { title: 'Sample API', version: '1.0.0' },
  paths: {
    '/users': {
      get: {
        operationId: 'listUsers',
        summary: 'List all users',
        responses: {
          '200': { description: 'Success' },
        },
      },
    },
  },
};

// Initialize a Forge instance with overlays applied
const forge = await init(spec);

// Access resolved operations and schemas
const op = forge.getVerbPath('listUsers');
console.log(op?.path, op?.verb); // /users get

CLI

Install the standalone Forge CLI to generate a TypeScript SDK from a bundled OpenAPI specification:

pnpm add --save-dev @cloudflare/forge-transformer-sdk-ts
pnpm exec forge openapi.json --out ./generated

Use - to read the OpenAPI document from stdin. Full generation requires Docker. The output directory contains the finalized OpenAPI document, generated SDK source, and sdk-map.json.

Development

# Install dependencies
pnpm install

# Run tests across all packages
pnpm test

# Typecheck
pnpm typecheck

# Lint and format
pnpm check

License

Apache-2.0 © Cloudflare, Inc.

forge (cloudflare/forge)

Searching Database…

1.1K ·GitHub
Forge
What is this?Forge is a schema-first OpenAPI code generation and surface tooling framework that resolves OpenAPI 3.x specs, applies JSONPath overlays, and generates typed SDKs, CLIs, runtime helpers and documentation.
Is it a single CLI app or something bigger?It is a plugin-based framework shipped as a monorepo of packages, built around a core OpenAPI resolver and JSONPath overlay engine, rather than one standalone app.
How do I generate an SDK from my OpenAPI spec?Install the standalone Forge CLI and point it at a bundled OpenAPI specification to generate a TypeScript SDK; you can also pipe the spec in via stdin using '-'.
Do I need Docker to use this?Full SDK generation requires Docker; the README specifies this is needed for the complete generation pipeline beyond basic CLI usage.
Can Forge generate SDKs for languages other than TypeScript right now?The monorepo includes workspace wrapper packages for Python, Go, Java, PHP, C#, Ruby, Rust and Swift, but the only generator the README documents as standalone is the TypeScript one.
What does the CLI output directory contain?It contains the finalized OpenAPI document, the generated SDK source code, and an sdk-map.json file.
What is astro-fern for?It is a generic Astro engine for rendering Fern-based API documentation, used by the docs-site package to build the API reference website.
Why does the monorepo include fern-forge?fern-forge is an astro-fern extension that validates and adapts Forge's OpenAPI metadata so it renders correctly in the Fern-based documentation site.
Can I generate SDKs in languages besides TypeScript?There are workspace wrapper packages for Python, Go, Java, PHP, C#, Ruby, Rust and Swift, but the documented standalone generator only covers TypeScript today.
What are similar projects?redoc, swagger-codegen, swagger-ui, swag, graphql-code-generator, openapi-generator, oar, mcp-extensions
Which topics is it in?openapi-specification, codegen, spec, api-documentation, code-generation, monorepo, cli-tool, sdk, documentation, rest-api, plugin, framework
Creator
cloudflare
Size
63.4 MB
Stars
1.1K
Updated
CommitOct 15Releaseopenapi@15656f084dd7a0ada54f8f659c749a7248254b9fOct 17
Age
26d
Commits · 90 Days