api — Functions

Functions and classes exported by this package.

signatureToSchema(signature)

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.

Signature

(signature: string) => OpenAPISchemaObject

Parameters

Returns — An OpenAPI schema object.

Example

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

extractSDKTypes(symbols)

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.

Signature

(symbols: ForgeSymbol[]) => SDKType[]

Parameters

Returns — An array of SDKType objects for public-facing type definitions.

Example

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

generateOpenAPISpec(config, sdkTypes, symbols)

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.

Signature

(config: ForgeConfig, sdkTypes: SDKType[], symbols?: ForgeSymbol[]) => OpenAPIDocument

Parameters

Returns — An OpenAPIDocument object.

Example

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(symbols)

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.

Signature

(symbols: ForgeSymbol[]) => ReferenceEntry[]

Parameters

Returns — An array of ReferenceEntry objects sorted by name.

Example

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

generateApi(config)

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

Signature

(config: ForgeConfig) => Promise<ForgeResult>

Parameters

Returns — A ForgeResult whose success field is true when the spec was written without error. symbols contains the full symbol graph from the walk step. errors and warnings are empty on success; file-system or walker errors are thrown rather than returned.

Example

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(signature)

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.

Signature

(signature: string) => OpenAPISchemaObject

Parameters

Returns — An OpenAPI schema object.

Example

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

extractSDKTypes(symbols)

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.

Signature

(symbols: ForgeSymbol[]) => SDKType[]

Parameters

Returns — An array of SDKType objects for public-facing type definitions.

Example

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

generateOpenAPISpec(config, sdkTypes, symbols)

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.

Signature

(config: ForgeConfig, sdkTypes: SDKType[], symbols?: ForgeSymbol[]) => OpenAPIDocument

Parameters

Returns — An OpenAPIDocument object.

Example

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(symbols)

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.

Signature

(symbols: ForgeSymbol[]) => ReferenceEntry[]

Parameters

Returns — An array of ReferenceEntry objects sorted by name.

Example

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

generateApi(config)

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

Signature

(config: ForgeConfig) => Promise<ForgeResult>

Parameters

Returns — A ForgeResult with success/failure and any diagnostics.

Example

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