Orientation
Content Processing
Search Infrastructure
Rendering and UI
Developer Tooling
How It Works
The following files were used as context for generating this wiki page:
API Schema Processing is a robust subsystem responsible for transforming, dereferencing, and visualizing complex API definitions (OpenAPI and AsyncAPI) into user-friendly documentation. At its heart, the system abstracts the hierarchical, reference-heavy nature of API specifications into a flat, navigable structure suitable for web-based UI rendering. It addresses the inherent complexity of resolving $ref pointers across massive documents, ensures consistent type representation, and handles the generation of representative example payloads for API requests.
The subsystem serves as the bridge between raw specification data (often deeply nested and non-deterministic) and the documentation components that render interactive UI elements like parameter tables, request body viewers, and nested schema explorations. By decoupling schema processing from the final rendering layer, the system allows for flexible consumption of API data while maintaining high performance through memoized data transformations and static generation utilities.
Interactions with adjacent components are mediated through clear interfaces: document loaders handle raw data retrieval, builders translate API structures into content pages, and UI components consume pre-processed "SchemaUI" data formats. This pipeline ensures that the core documentation engine remains agnostic of specific API versions or protocol-specific implementation details while providing a seamless developer experience for documentation consumers.
The dereferencing mechanism is a recursive algorithm that traverses JSON Schema or OpenAPI definitions to resolve references ($ref) into their actual, defined objects. This process is critical for flattening structures so that the documentation UI can perform lookup operations without needing to perform on-the-fly network or document-wide resolutions.
The primary entry point, dereferenceSync in packages/api-docs/src/schema/dereference.ts, utilizes structuredClone to create a deep copy of the document, ensuring operations are performed on isolated data structures. The algorithm maintains a visitedNodes Set to prevent infinite loops (a common issue in circular schema definitions). When an object containing $ref is encountered, it is passed to resolveRefSync which parses the JSON pointer and retrieves the target node from the root document.
Important
The dereferenceSync function employs a preserveRef callback option. If this function returns true for a given pointer, the algorithm will stop inlining, preserving the original reference pointer in the final object instead of replacing it with the dereferenced content.
Generating example request data from a schema is handled by a recursive traverse function, inspired by the logic found in openapi-sampler. This process is non-trivial because JSON Schema allows for polymorphic constructs (oneOf, anyOf, allOf) and conditional logic (if/then) that make payload inference complex.
The sample generator uses a seenObjectStack and refResolving cache to handle recursive or circular references. When traversing an object, the generator respects flags such as skipReadOnly and skipWriteOnly, which are crucial for ensuring the generated example matches the actual intended usage (e.g., in a GET request, read-only fields should be included; in a POST request, write-only fields take precedence).
When working with allOf in JSON Schema, the system must merge properties from multiple schema definitions. The mergeAllOf function in packages/api-docs/src/schema/merge.ts acts as a recursive processor that performs set intersection on schema constraints.
For instance, when merging two objects, it doesn't just clone the objects; it executes a structural intersection. Key fields like minimum, maximum, minLength, and maxLength are computed using Math.max or Math.min to ensure the final schema maintains the strictest possible constraint.
Note
The intersection logic for properties in packages/api-docs/src/schema/merge.ts is additive. If a property exists in both schemas being merged, intersection is called recursively on those properties, ensuring deep consistency.
The documentation UI frequently needs to display the "Type" of a field (e.g., array<string> | null). The schemaToString utility handles the conversion of a JSON Schema object into a human-readable type descriptor.
This function uses a bitwise FormatFlags enum (None = 0, UseAlias = 1) to determine whether to use the schema's raw type or its title alias (often defined by a $ref path). This allows the UI to render "Pet" instead of "object" when appropriate.
The PagesBuilder system provides a fluent API for defining how an OpenAPI document is sliced into discrete documentation pages. The createAutoPreset function is a high-level utility that abstracts this builder to allow automatic page generation based on configuration (per: 'operation' | 'tag' | 'file').
The group method within the builder handles the sorting and hierarchical organization of operation entries. When groupBy is set to tag, the builder traverses the tags defined in the document, filters operations associated with that tag, and constructs a virtual folder path for each group.
Sources: packages/api-docs/src/schema/dereference.ts:19-65, packages/api-docs/src/schema/to-string.ts:3-6
The following demonstrates how to initialize a document and process it through the builder.
import { createOpenAPI } from '@fumadocs/openapi/server';
import { createAutoPreset } from '@fumadocs/openapi/utils/pages/preset-auto';
// 1. Initialize server with an OpenAPI spec
const server = createOpenAPI({
input: ['https://petstore.swagger.io/v2/swagger.json']
});
// 2. Configure automatic page generation
const options = createAutoPreset({
per: 'operation',
groupBy: 'tag'
});
// 3. Generate static pages
const source = await server.staticSource(options);
// Now 'source.files' contains the virtual filesystem paths and page props