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
Что это?Forge — schema-first фреймворк генерации кода и тулинга поверх OpenAPI, который резолвит спецификации OpenAPI 3.x, применяет JSONPath-оверлеи и генерирует типизированные SDK, CLI, runtime-хелперы и документацию.
Это одно CLI-приложение или нечто большее?Это фреймворк на плагинах, поставляемый как монорепозиторий пакетов и построенный вокруг ядра-резолвера OpenAPI и движка JSONPath-оверлеев, а не одно standalone-приложение.
Как сгенерировать SDK из моей OpenAPI-спецификации?Установите standalone Forge CLI и укажите ему встроенную OpenAPI-спецификацию, чтобы сгенерировать TypeScript SDK; спецификацию можно также передать по stdin, используя '-'.
Нужен ли Docker, чтобы этим пользоваться?Полная генерация SDK требует Docker; в README уточняется, что это нужно для полного конвейера генерации за пределами базового использования CLI.
Может ли Forge сейчас генерировать SDK для языков, отличных от TypeScript?В монорепозитории есть wrapper-пакеты workspace для Python, Go, Java, PHP, C#, Ruby, Rust и Swift, но единственный генератор, описанный в README как standalone, — генератор TypeScript.
Что содержит выходной каталог CLI?В нём лежат финализированный OpenAPI-документ, сгенерированный исходный код SDK и файл sdk-map.json.
Для чего нужен astro-fern?Это универсальный движок Astro для рендеринга API-документации на основе Fern, используемый пакетом docs-site для сборки сайта со справочником API.
Зачем в монорепозитории fern-forge?fern-forge — расширение astro-fern, которое валидирует и адаптирует OpenAPI-метаданные Forge, чтобы они корректно отображались на сайте документации на основе Fern.
Можно генерировать SDK на языках, кроме TypeScript?Существуют wrapper-пакеты workspace для Python, Go, Java, PHP, C#, Ruby, Rust и Swift, но документированный standalone-генератор сегодня покрывает только TypeScript.
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@e91e65be9898b6bc400231f36ce77e8e7d5a02abOct 17
Age
27d
Commits · 90 Days