api — Examples

All usage examples from the package, aggregated for quick reference.

signatureToSchema()

Maps a TypeScript type signature string to an OpenAPI 3.2 schema object. Handles common primitives, arrays, unions, Record<K, V>, and falls back to { type: "object" } for anything it cannot parse.

View in API reference

import { signatureToSchema } from "@forge-ts/api";
const schema = signatureToSchema("string[]");
// { type: "array", items: { type: "string" } }

extractSDKTypes()

Extracts SDK-relevant types (interfaces, type aliases, classes, enums) from a list of ForgeSymbol objects. Only exported symbols whose visibility is not Visibility.Internal or Visibility.Private are included.

View in API reference

import { extractSDKTypes } from "@forge-ts/api";
const sdkTypes = extractSDKTypes(symbols);
console.log(sdkTypes.length); // number of public SDK types

generateOpenAPISpec()

Generates a production-quality OpenAPI 3.2 document from the extracted SDK types. The document is populated with: - An info block sourced from the config or reasonable defaults. - A components.schemas section with one schema per exported type. - tags derived from unique source file paths (grouping by file). - Visibility filtering: @internal symbols are never emitted. - HTTP paths are extracted from @route tags and appropriately mapped.

View in API reference

import { generateOpenAPISpec } from "@forge-ts/api";
import { extractSDKTypes } from "@forge-ts/api";
const spec = generateOpenAPISpec(config, extractSDKTypes(symbols), symbols);
console.log(spec.openapi); // "3.2.0"

buildReference()

Builds a structured API reference from a list of exported symbols. Unlike the minimal stub, this version includes nested children (class methods, interface properties) and all available TSDoc metadata. Symbols with Visibility.Internal or Visibility.Private are excluded from the top-level results. Children with private/internal visibility are also filtered out.

View in API reference

import { buildReference } from "@forge-ts/api";
const entries = buildReference(symbols);
console.log(entries[0].name); // first symbol name, alphabetically

generateApi()

Runs the API generation pipeline: walk → extract → generate → write.

View in API reference

import { loadConfig } from "@forge-ts/core";
import { generateApi } from "@forge-ts/api";

const config = await loadConfig();
const result = await generateApi(config);
console.log(result.success); // true if the spec was written successfully

index.ts

OpenAPI 3.2 spec generator and structured API reference builder for forge-ts. Inspects the ForgeSymbol[] graph produced by @forge-ts/core, extracts TypeScript types annotated with @route tags, maps their signatures to JSON Schema objects, and writes a complete OpenAPI 3.2 document alongside a structured API reference catalogue. Integrates with the broader documentation pipeline via config.api.openapiPath.

View in API reference

import { loadConfig } from "@forge-ts/core";
import { generateApi } from "@forge-ts/api";

const config = await loadConfig();
const result = await generateApi(config);
console.log(result.success); // true if the spec was written successfully

signatureToSchema()

Maps a TypeScript type signature string to an OpenAPI 3.2 schema object. Handles common primitives, arrays, unions, Record<K, V>, and falls back to { type: "object" } for anything it cannot parse.

View in API reference

import { signatureToSchema } from "@forge-ts/api";
const schema = signatureToSchema("string[]");
// { type: "array", items: { type: "string" } }

extractSDKTypes()

Extracts SDK-relevant types (interfaces, type aliases, classes, enums) from a list of ForgeSymbol objects. Only exported symbols whose visibility is not Visibility.Internal or Visibility.Private are included.

View in API reference

import { extractSDKTypes } from "@forge-ts/api";
const sdkTypes = extractSDKTypes(symbols);
console.log(sdkTypes.length); // number of public SDK types

generateOpenAPISpec()

Generates a production-quality OpenAPI 3.2 document from the extracted SDK types. The document is populated with: - An info block sourced from the config or reasonable defaults. - A components.schemas section with one schema per exported type. - tags derived from unique source file paths (grouping by file). - Visibility filtering: @internal symbols are never emitted. - HTTP paths are extracted from @route tags and appropriately mapped.

View in API reference

import { generateOpenAPISpec } from "@forge-ts/api";
import { extractSDKTypes } from "@forge-ts/api";
const spec = generateOpenAPISpec(config, extractSDKTypes(symbols), symbols);
console.log(spec.openapi); // "3.2.0"

buildReference()

Builds a structured API reference from a list of exported symbols. Unlike the minimal stub, this version includes nested children (class methods, interface properties) and all available TSDoc metadata. Symbols with Visibility.Internal or Visibility.Private are excluded from the top-level results. Children with private/internal visibility are also filtered out.

View in API reference

import { buildReference } from "@forge-ts/api";
const entries = buildReference(symbols);
console.log(entries[0].name); // first symbol name, alphabetically

generateApi()

Runs the API generation pipeline: walk → extract → generate → write.

View in API reference

import { generateApi } from "@forge-ts/api";
const result = await generateApi(config);
console.log(result.success); // true if spec was written successfully