OpenAPI Document Generation

Copyexport * from './generate-file';
export type { MediaAdapter } from '@/requests/media/adapter';
export type { RenderContext } from './types';
export type {
  OperationOutput,
  OutputEntry,
  OutputGroup,
  PageOutput,
  PagesBuilder,
  PagesBuilderConfig,
  WebhookOutput,
  OperationItem,
  WebhookItem,
  GeneratedPageProps,
} from './utils/pages/builder';
export type { SchemaToPagesOptions } from './utils/pages/preset-auto';
export type { OpenAPIV3_2, OpenAPIV3_1, OpenAPIV3, OpenAPIV2, OpenAPI } from '@/types/openapi';

Copyexport async function loadDocument(input: string | Document): Promise<{
  bundled: Document;
}> {
  try {
    let bundled = await bundle<Document>(input);
    bundled = upgrade(bundled, '3.2') as Document;
    return { bundled };
  } catch (e) {
    throw new Error(`[OpenAPI] Failed to resolve input: ${input}`, {
      cause: e,
    });
  }
}

Copyinterface BaseEntry {
  path: string;
  schemaId: string;
  info: {
    title: string;
    description?: string;
    deprecated?: boolean;
  };
}
 
export interface OperationOutput extends BaseEntry {
  type: 'operation';
  item: OperationItem;
}
 
export interface WebhookOutput extends BaseEntry {
  type: 'webhook';
  item: WebhookItem;
}
 
export interface PageOutput extends BaseEntry {
  type: 'page';
  operations: OperationItem[];
  webhooks: WebhookItem[];
  /** tag info if the page is generated from a tag. */
  tag?: TagObject;
}
 
export interface OutputGroup extends BaseEntry {
  type: 'group';
  entries: OutputEntry[];
  /** tag info if the group is generated from a tag. */
  tag?: TagObject;
}
 
export interface WebhookItem {
  /**
   * webhook name in `webhooks`
   */
  name: string;
  method: HttpMethods;
}
 
export interface OperationItem {
  /**
   * the path of operation in `paths`
   */
  path: string;
  /**
   * the HTTP method of operation
   */
  method: HttpMethods;
}
 
export type OutputEntry = PageOutput | OperationOutput | WebhookOutput | OutputGroup;

Copyexport function fromSchema(
  schemaId: string,
  bundled: Document,
  config: PagesBuilderConfig,
): OutputEntry[] {
  const files: OutputEntry[] = [];
  const { toPages } = config;
 
  toPages({
    id: schemaId,
    document: bundled,
    dereferenceShallow: (s) => dereferenceShallow(s, bundled),
    create(entry) {
      files.push(entry);
    },
    extract() {
      const result: ExtractedInfo = { webhooks: [], operations: [] };
 
      for (const [path, pathItem] of Object.entries(bundled.paths ?? {})) {
        if (!pathItem) continue;
 
        for (const methodKey of methodKeys) {
          if (!pathItem[methodKey]) continue;
 
          result.operations.push({
            method: methodKey,
            path,
            tags: pathItem[methodKey]?.tags,
          });
        }
      }
 
      for (const [name, _pathItem] of Object.entries(bundled.webhooks ?? {})) {
        const pathItem = dereferenceShallow(_pathItem, bundled);
        if (!pathItem) continue;
 
        for (const methodKey of methodKeys) {
          if (!pathItem[methodKey]) continue;
 
          result.webhooks.push({
            method: methodKey,
            name,
            tags: pathItem[methodKey]?.tags,
          });
        }
      }
 
      return result;
    },
    routePathToFilePath(path) {
      return path
        .toLowerCase()
        .replaceAll('.', '-')
        .split('/')
        .flatMap((v) => {
          if (v.startsWith('{') && v.endsWith('}')) return v.slice(1, -1);
          if (v.length === 0) return [];
          return v;
        })
        .join('/');
    },

Copyexport function createOpenAPI(options: OpenAPIOptions = {}): OpenAPIServer {
  const { disableCache = false } = options;
  const schemaMap = new Map<string, Promise<LoadedDocument>>();
 
  let resolvedInput: SchemaRecord = {};
  if (Array.isArray(options.input)) {
    for (const item of options.input) resolvedInput[item] = item;
  } else if (options.input) {
    resolvedInput = options.input;
  }
 
  function getSchema(schemaId: string): Promise<LoadedDocument> {
    if (!(schemaId in resolvedInput)) {
      console.warn(
        `[Fumadocs OpenAPI] the document "${schemaId}" is not listed in the input array, this may be unexpected and won't be cached properly.`,
      );
      // do not cache unlisted documents
      return loadDocument(schemaId);
    }
 
    if (!disableCache) {
      const cached = schemaMap.get(schemaId);
      if (cached) return cached;
    }
 
    const raw = resolvedInput[schemaId];
    const output = Promise.resolve(typeof raw === 'function' ? raw() : raw).then(loadDocument);
    if (!disableCache) schemaMap.set(schemaId, output);
    return output;
  }
 
  async function getSchemas(): Promise<Record<string, LoadedDocument>> {
    const entries = await Promise.all(
      Object.keys(resolvedInput).map(async (k) => [k, await getSchema(k)]),
    );
    return Object.fromEntries(entries);
  }
 
  async function getVirtualFiles(server: OpenAPIServer, options: OpenAPISourceOptions) {
    const { baseDir = '', meta = false } = options;
    const { createAutoPreset } = await import('@/utils/pages/preset-auto');
    const { fromSchema } = await import('@/utils/pages/builder');
    const files: VirtualFile<{
      pageData: OpenAPIPageData;
      metaData: MetaData;
    }>[] = [];
 
    const schemas = await server.getSchemas();
    const builderOptions = createAutoPreset(options);
 
    for (const [id, schema] of Object.entries(schemas)) {
      const list = fromSchema(id, schema.bundled, builderOptions);
 
      onEntries(list);
 
      function onEntry(entry: PageOutput | OperationOutput | WebhookOutput) {
        const props = getPageProps(entry);
 
        files.push({
          type: 'page',
          path: `${baseDir}/${entry.path}`,
          data: {
            ...entry.info,
            getAPIPageProps() {
              return this.getOpenAPIPageProps();
            },
            getClientAPIPageProps() {
              return this.getOpenAPIPageProps();
            },
            getOpenAPIPageProps() {
              return {
                payload: {
                  bundled: schema.bundled,
                  proxyUrl: server.options.proxyUrl,
                },
                ...props,
              };
            },
            getSchema() {
              return {

Copyexport function toStaticData(
  page: GeneratedPageProps,
  doc: Document,
): {
  toc: TOCItemType[];
  structuredData: StructuredData;
} {

Copyconst slugger = new Slugger();
const toc: TOCItemType[] = [];
const structuredData: StructuredData = { headings: [], contents: [] };
 
function pathItem(item: OperationObject, defaultTitle: string) {
  if (page.showTitle && item.operationId) {
    const title = item.summary || (item.operationId ? idToTitle(item.operationId) : defaultTitle);
    const id = slugger.slug(title);
 
    toc.push({
      depth: 2,
      title,
      url: `#${id}`,
    });
    structuredData.headings.push({
      content: title,
      id,
    });
  }
 
  if (item.description)
    structuredData.contents.push({
      content: item.description,
      heading: structuredData.headings.at(-1)?.id,
    });
}

Copyfor (const item of page.operations ?? []) {
  const operation = dereferenceShallow(doc.paths?.[item.path], doc)?.[item.method];
  if (!operation) continue;
 
  pathItem(operation, item.path);
}
 
for (const item of page.webhooks ?? []) {
  const webhook = dereferenceShallow(doc.webhooks?.[item.name], doc)?.[item.method];
  if (!webhook) continue;
 
  pathItem(webhook, item.name);
}
 
return { toc, structuredData };

Copy  /**
   * The version of algorithm used to generate file paths.
   *
   * v1: Fumadocs OpenAPI v8
   * v2: Fumadocs OpenAPI v9
   *
   * @defaultValue v2
   */
  algorithm?: 'v2' | 'v1';
}

Copy  if (result.type === 'operation') {
    const operation = this.document.paths![result.item.path]![result.item.method]!;
 
    if (algorithm === 'v2' && operation.operationId) {
      return operation.operationId;
    }
 
    return path.join(
      this.routePathToFilePath(result.item.path),
      result.item.method.toLowerCase(),
    );
  }
 
  const hook = dereferenceShallow(this.document.webhooks![result.item.name], this.document)[
    result.item.method
  ]!;
 
  if (algorithm === 'v2' && hook.operationId) {
    return hook.operationId;
  }
 
  return slugify(result.item.name);
};

Copyexport function toText(
  entry: PageOutput | OperationOutput | WebhookOutput,
  doc: Document,
  options: PagesToTextOptions = {},
) {
  const { frontmatter, includeDescription = false } = options;
  const extend = frontmatter?.(
    entry.info.title,
    entry.info.description,
    entry.type === 'page'
      ? entry.tag
        ? { type: 'tag', tag: entry.tag }
        : { type: 'file' }
      : { type: 'operation' },
  );
  const pageProps = getPageProps(entry);
  if (!includeDescription) {
    pageProps.showDescription = false;
  }
 
  let meta: InternalOpenAPIMeta = {
    preload: [entry.schemaId],
  };
  if (entry.type === 'operation' || entry.type === 'webhook') {
    const operation = entry.item;
 
    meta.method = operation.method.toUpperCase();
    meta.webhook = entry.type === 'webhook';
    meta.deprecated = entry.info.deprecated;
  }
 
  const data = toStaticData(pageProps, doc);
 
  return generateDocument(
    {
      title: entry.info.title,
      description: !includeDescription ? entry.info.description : undefined,
      full: true,
      ...extend,
      _openapi: {
        ...meta,
        ...data,
        ...(extend?._openapi as object | undefined),
      },
    },
    pageContent(pageProps),
    options,
  );
}

Copyfunction pageContent({
  showTitle,
  showDescription,
  document,
  webhooks,
  operations,
}: GeneratedPageProps): string {
  const propStrs: string[] = [`document=${doubleQuote(document)}`];
 
  // filter extra properties in props
  if (webhooks) {
    propStrs.push(
      `webhooks={${JSON.stringify(
        webhooks.map(
          (item) =>
            ({
              name: item.name,
              method: item.method,
            }) satisfies WebhookItem,
        ),
      )}}`,
    );
  }
  if (operations) {
    propStrs.push(
      `operations={${JSON.stringify(
        operations.map(
          (item) =>
            ({
              path: item.path,
              method: item.method,
            }) satisfies OperationItem,
        ),
      )}}`,
    );
  }
  if (showTitle) {
    propStrs.push(`showTitle`);
  }
  if (showDescription) {
    propStrs.push(`showDescription`);
  }
 
  return `export default function Layout(props) {
  const { APIPage, OpenAPIPage } = props.components ?? {};
  // "APIPage" is the old name from v10, this allows both for backward compatibility
  const Comp = OpenAPIPage ?? APIPage;
  return (
    <>
      {props.children}
      <Comp ${propStrs.join(' ')} />
    </>
  );
}`;
}

Copyexport function generateDocument(
  frontmatter: unknown,
  content: string,
  options: PagesToTextOptions,
): string {
  const { addGeneratedComment = true, imports } = options;
  const out: string[] = [];
  const banner = dump(removeUndefined(frontmatter as object)).trimEnd();
  if (banner.length > 0) out.push(`---\n${banner}\n---`);
 
  if (addGeneratedComment) {
    let commentContent =
      'This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.';
 
    if (typeof addGeneratedComment === 'string') {
      commentContent = addGeneratedComment;
    }
 
    commentContent = commentContent.replaceAll('/', '\\/');
    out.push(`{/* ${commentContent} */}`);
  }
 
  if (imports) {
    out.push(
      ...imports
        .map((item) => `import { ${item.names.join(', ')} } from ${doubleQuote(item.from)};`)
        .join('\n'),
    );
  }
 
  out.push(content);
  return out.join('\n\n');
}

Copyexport async function generateFiles(options: Config): Promise<void> {
  if (options.watch) {
    const { watch } = await import('chokidar');
    const subOptions: Config = { ...options, watch: false };
 
    await generateFiles(subOptions);
    const targets = options.input._getWatchPaths();
    console.log(`[Fumadocs OpenAPI] watching ${targets.join(', ')}`);
    watch(targets, {
      ignoreInitial: true,
    }).on('all', () => generateFiles(subOptions));
    return;
  }
 
  const files = await generateFilesOnly(options);
 
  await Promise.all(
    files.map(async (file) => {
      const filePath = path.join(options.output, file.path);
 
      await mkdir(path.dirname(filePath), { recursive: true });
      await writeFile(filePath, file.content);
      console.log(`Generated: ${filePath}`);
    }),
  );
}

Copyif (options.watch) {
  const { watch } = await import('chokidar');
  const subOptions: Config = { ...options, watch: false };
 
  await generateFiles(subOptions);
  const targets = options.input._getWatchPaths();
  console.log(`[Fumadocs OpenAPI] watching ${targets.join(', ')}`);
  watch(targets, {
    ignoreInitial: true,
  }).on('all', () => generateFiles(subOptions));
  return;
}

Copyexport async function generateFilesOnly(
  options: DistributiveOmit<Config, 'output'>,
): Promise<OutputFile[]> {
  const schemas = await options.input.getSchemas();
 
  const files: OutputFile[] = [];
  const generated: Record<string, OutputFile[]> = {};
  const generatedEntries: Record<string, OutputEntry[]> = {};
 
  const entries = Object.entries(schemas);
  if (entries.length === 0) {
    throw new Error('No input files found.');
  }
  const preset = createAutoPreset(options);
  for (const [id, schema] of entries) {
    const entries = fromSchema(id, schema.bundled, preset);
    const schemaFiles: OutputFile[] = [];
 
    generatedEntries[id] = entries;
    function scan(entry: OutputEntry) {
      if (entry.type === 'group') {
        for (const child of entry.entries) scan(child);
        return;
      }
 
      schemaFiles.push({
        path: entry.path,
        content: toText(entry, schema.bundled, options),
      });
    }
 
    for (const entry of entries) scan(entry);
    generated[id] = schemaFiles;
    files.push(...schemaFiles);
  }
 
  const context: BeforeWriteContext = {
    generated,
    generatedEntries,
  };
 
  if (options.index) {
    files.push(...writeIndexFiles(context, options));
  }
 
  if (options.meta) {
    files.push(...generateMeta(context, options.meta === true ? {} : options.meta));
  }
 
  await options.beforeWrite?.call(context, files);
  return files;
}

Copyfunction generateMeta(context: BeforeWriteContext, options: MetaOptions): OutputFile[] {
  const files: OutputFile[] = [];
  const folderStyle = options.folderStyle ?? 'folder';
 
  function scan(entries: OutputEntry[], parent?: OutputGroup) {
    const pages: string[] = [];
 
    for (const entry of entries) {
      const relativePath = PathUtils.slash(
        parent ? path.relative(parent.path, entry.path) : entry.path,
      );
 
      if (entry.type === 'group') {
        scan(entry.entries, entry);
 
        if (folderStyle === 'folder') {
          pages.push(relativePath);
        } else {
          pages.push(`---${entry.info.title}---`, `...${relativePath}`);
        }
      } else {
        pages.push(relativePath.slice(0, -path.extname(entry.path).length));
      }
    }
 
    if (pages.length === 0) return;
    files.push({
      path: parent ? path.join(parent.path, 'meta.json') : 'meta.json',
      content: JSON.stringify(
        {
          title: parent?.info.title,
          description: parent?.info.description,
          pages,
        },
        null,
        2,
      ),
    });
  }
 
  for (const entries of Object.values(context.generatedEntries)) {
    scan(entries);
  }
 
  return files;
}