API-Dokumentation

Die Option api erzeugt Markdown aus öffentlichen TypeScript-Einstiegspunkten: abgeleitete Typen, Signaturen, Überladungen, JSDoc und unterstützte geerbte oder zusammengesetzte Eigenschaften. So entsteht Ardos eigene API-Referenz. Für REST-APIs kannst du stattdessen eine OpenAPI-Spezifikation verwenden.

Installation

Die Integration verwendet einen festgelegten TypeScript-7.1-Nightly-Build und den OXC-Parser:

pnpm add -D typescript@7.1.0-dev.20261011.1 oxc-parser@^0.155.0

Ardo liest Deklarationen über die native API von TypeScript 7.1, die auch das Projekt typprüft. TypeScript 7.0 funktioniert nicht: Seiner noch instabilen nativen API fehlen die benötigten Snapshot-, Emit- und Modulauflösungsaufrufe. Unterstützt wird ein festgelegter Nightly-Build, keine veröffentlichte 7.1-Beta. Projekte mit dem Alias @typescript/native funktionieren weiterhin.

Konfiguration

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.api.json",
    out: "api-reference",
    title: "API Reference",
  },
})

Die Konfiguration gehört in ardo.config.ts. Pfade sind relativ zur Dokumentationswurzel; out muss unterhalb des Routenverzeichnisses liegen. api: true nutzt ./src/index.ts, ./tsconfig.json und die oben gezeigten Standardwerte für Ausgabe und Titel. api ist das Backend für API-Dokumentation aus Quellcode.

Wähle eine TypeScript-Konfiguration, die öffentliche Einstiegspunkte und ihre Abhängigkeiten enthält. Du kannst die Dokumentationsprüfung auf den öffentlichen Graphen begrenzen:

{
  "extends": "./tsconfig.json",
  "files": ["src/index.ts"],
  "include": []
}

Ergänze erforderliche globale Deklarationsdateien ebenfalls in files. Ardo aktiviert geprüfte Deklarationsausgabe und hält Kommentare im Speicher, auch bei noEmit oder removeComments. Deine Konfigurationsdatei bleibt unverändert; Deklarationen müssen nicht auf die Festplatte geschrieben werden.

Importpfade

Ordne bei Unterpfadexporten jedem Importpfad seinen Einstiegspunkt zu. Jede Seite zeigt dann den passenden Import; der Index gruppiert nach Importpfad:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: {
      "my-lib/ui": "./src/ui/index.ts",
      "my-lib/hooks": "./src/hooks/index.ts",
    },
    tsconfig: "./tsconfig.api.json",
  },
})

Wird eine Deklaration mehrfach exportiert, gehört sie zum ersten Einstiegspunkt. Ardos API-Referenz nutzt dies für ardo/ui, ardo/runtime und ardo/config.

Inhalt der Referenzseiten

Eine Funktion mit großem Anfangsbuchstaben gilt als React-Komponente. Ihre Seite zeigt Import, JSX-Beispiel mit Pflicht-Props und eine Tabelle aller Props. Ein zur Komponente benannter Props-Typ, etwa ButtonProps für Button, erhält keine eigene Seite, wenn die Tabelle alle Props enthält. Links darauf führen zur Props-Tabelle der Komponente.

Funktionen, Hooks und Typen zeigen Signatur oder Definition. Typnamen in Tabellen verlinken ihre Seiten. JSDoc-Beschreibungen, @example, @remarks, @deprecated, @default und {@link Name} erscheinen auf der Seite.

Mehrere Pakete

Übergib ein Array, wenn Pakete eigene TypeScript-Konfigurationen oder getrennte Präfixe für API-Routen benötigen:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: [
    {
      entryPoints: ["./packages/alpha/src/index.ts"],
      tsconfig: "./packages/alpha/tsconfig.json",
      out: "api-reference/alpha",
    },
    {
      entryPoints: ["./packages/beta/src/index.ts"],
      tsconfig: "./packages/beta/tsconfig.json",
      out: "api-reference/beta",
    },
  ],
})

Ausgabeverzeichnisse müssen auch ohne Beachtung der Großschreibung verschieden sein und dürfen einander nicht enthalten. Jedes Projekt nimmt an anfänglicher Routenerkennung und Entwicklungsaktualisierungen teil. Scheitert die Initialisierung, werden alle dabei gestarteten Compiler-Sitzungen geschlossen. Das ist keine TypeScript-Solution-Builder-Orchestrierung.

Build und Entwicklung

ardo build erzeugt API-Markdown vor der Routenerkennung, ohne separaten Deklarationsbuild oder Dateien auf der Festplatte. Ein anfänglicher Compilerfehler lässt die Generierung scheitern. Im Entwicklungsmodus aktualisiert die laufende native Sitzung die Dokumentation bei Änderungen an Quellen, Abhängigkeiten und Konfiguration. Typfehler erscheinen im Overlay; die letzten erfolgreichen Seiten bleiben erhalten. Nach der Korrektur läuft die Generierung weiter.

Unveränderte Markdown-Dateien behalten ihren Änderungszeitpunkt. Entfernte Exporte verlieren ihre Seiten. Halte eigene Inhalte außerhalb des generierten Verzeichnisses: Ardo ersetzt keine nicht leeren Verzeichnisse ohne Generierungsmarkierung.

Vite ignoriert normalerweise Dateien in node_modules. Starte nach Installation oder Änderungen dort den Entwicklungsserver neu.

Programmatische Verwendung

Bei einem einzelnen Generierungslauf wird die Compiler-Sitzung automatisch geschlossen:

import { generateNativeDocs } from "ardo/api"

const result = await generateNativeDocs(
  { entryPoints: ["./src/index.ts"], tsconfig: "./tsconfig.api.json" },
  "./app/routes"
)

Hosts mit eigener Dateiüberwachung können NativeApiProject wiederverwenden, extract oder generate mit Listen changed, created und deleted aufrufen und beim Beenden close() ausführen. Benachrichtigungen verwenden absolute Pfade. Derselbe native Compiler übernimmt Initialisierung und Aktualisierungen.

Aktuelle Grenzen

Geerbte Props werden auf der Seite aufgefächert, auch aus Namespaces wie React. DOM-Attribute erscheinen neben eigenen Props; generische Argumente, ausgelassene Mitglieder und eigene Überschreibungen bleiben erhalten.

Typausdrücke bleiben erhalten; nicht unterstützte Eigenschaftserweiterungen werden gemeldet. Beliebige gemappte oder bedingte Typen, vollständiges TSDoc, Namespace-Seiten, Seiten für export =, global installierte Namespace-Mitglieder und Originalquelllinks bleiben Migrationsarbeit. Verweise auf nicht unterstützte globale Namespace-Mitglieder melden eine unvollständige Erweiterung. Jedes Projekt hat eine eigene Sitzung; Solution-Builder-Verhalten wird nicht angeboten.

Schreibe Mitglieder-JSDoc auf eine eigene Zeile vor dem Mitglied. Kommentare auf derselben Zeile wie eine öffnende Klammer können verloren gehen. Löst dieselbe Paketanfrage innerhalb einer Datei im Import- und Require-Modus verschiedene Deklarationen auf, meldet der Extraktor eine unvollständige Erweiterung, statt eine womöglich falsche Deklaration zu wählen.

Für Projekte mit der entfernten TypeDoc-Integration gilt die TypeDoc-Migration. Der native Weg nutzt den offiziellen TypeScript-Node-Client und benötigt keine eigenen Go-Bindings.

OpenAPI-Spezifikationen

Ardo wandelt lokale OpenAPI-3.0- oder -3.1-Spezifikationen in statische MDX-Referenzen um. Die Seiten nutzen dieselben Routen, Seitenleisten, Suche, Sitemap, Linkprüfung und LLM-Ausgaben wie die übrige Dokumentation.

Lokale Spezifikation konfigurieren

Halte die Spezifikation im Repository und ergänze ihren relativen Pfad in ardo.config.ts. Füge openapi zur bestehenden Konfiguration hinzu:

ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "Pet API",
  openapi: {
    spec: "./openapi.yaml",
    out: "api",
  },
})

spec akzeptiert .json, .yaml und .yml. Der Standard für out ist api: Der Index liegt unter /api, Operationen nach Tags gruppiert etwa unter /api/pets/get-pets.

Generierte Inhalte

Die statische Referenz enthält zunächst:

• API-Titel und Beschreibung;
• HTTP-Methode und Pfad;
• Gruppierung nach Tags;
• Zusammenfassung oder Beschreibung der Operation;
• deklarierte Parameter und Pflichtfeldmarkierungen;
• deklarierte Antwortstatus und Beschreibungen.

Generierte Verzeichnisse sind als Ardo-verwaltet markiert. Bearbeite die OpenAPI-Quelle, nicht die erzeugten MDX-Dateien.

Bewusst statisch

Der Build lädt keine entfernten Spezifikationen, sendet keine API-Anfragen, speichert keine Zugangsdaten und rendert keine interaktive Anfragekonsole. So bleiben Builds reproduzierbar und statische Deployments sicher. Ein projektspezifischer Playground kann später als eigene React-Komponente ergänzt werden, ohne den Vertrag der Referenz zu ändern.

Prüfen

Führe nach einer Spezifikationsänderung den üblichen Dokumentationsbuild aus:

pnpm build

Ein ungültiges Dokument, eine nicht unterstützte OpenAPI-Hauptversion oder eine Spezifikation ohne Objektstruktur lässt den Build mit einer hilfreichen Ardo-Fehlermeldung scheitern.