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 优先的 OpenAPI 代码生成与接口工具框架，可以解析 OpenAPI 3.x 规范、应用 JSONPath overlay，并生成带类型的 SDK、CLI、运行时辅助函数和文档。
它是单个 CLI 应用，还是更大的东西？它是一个基于插件的框架，以 monorepo 多包形式发布，围绕一个核心 OpenAPI 解析器和 JSONPath overlay 引擎构建，而不是单个独立应用。
怎么从我的 OpenAPI 规范生成 SDK？安装独立的 Forge CLI，让它指向一个捆绑的 OpenAPI 规范来生成 TypeScript SDK；也可以用 '-' 通过 stdin 管道传入规范。
用这个需要 Docker 吗？完整的 SDK 生成需要 Docker；README 说明，在基本 CLI 用法之外，完整的生成流水线需要它。
Forge 现在能为 TypeScript 以外的语言生成 SDK 吗？monorepo 里有面向 Python、Go、Java、PHP、C#、Ruby、Rust 和 Swift 的 workspace 包装包，但 README 中记载为可独立使用的生成器只有 TypeScript 那一个。
CLI 的输出目录里有什么？里面有最终定稿的 OpenAPI 文档、生成的 SDK 源代码，以及一个 sdk-map.json 文件。
astro-fern 是干什么的？它是一个用于渲染基于 Fern 的 API 文档的通用 Astro 引擎，docs-site 包用它来构建 API 参考网站。
monorepo 里为什么有 fern-forge？fern-forge 是一个 astro-fern 扩展，负责校验并适配 Forge 的 OpenAPI 元数据，让它在基于 Fern 的文档站点中正确渲染。
能生成 TypeScript 以外语言的 SDK 吗？有面向 Python、Go、Java、PHP、C#、Ruby、Rust 和 Swift 的 workspace 包装包，但文档记载的独立生成器目前只覆盖 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@15656f084dd7a0ada54f8f659c749a7248254b9fOct 17
Age
26d
Commits · 90 Days