Die Sektion deklarieren

Eine Referenz ist eine generierte Sektion: Eine Quelle nennt ein Artefakt und den Typ, der es liest, und die Seiten folgen daraus.

export default defineAppConfig({
  duxt: {
    sources: [
      {
        path: 'docs',
        generated: [
          {
            type: 'openapi',
            path: 'openapi.yaml',
            label: 'API'
          }
        ]
      }
    ]
  }
})

Die Felder, die eine Deklaration nimmt, sind für jeden Typ dieselben und stehen in Quellen. openapi nennt keine eigene Option; was es beantwortet, steht unten.

#Was daraus entsteht

/api                      die Übersicht, aus `info`
/api/<tag>                eine Seite pro Tag
/api/<tag>/<operation>    eine Seite pro Operation, mit dem Client

Eine Operation ohne Tag landet in einer Standardgruppe, 3.1-Webhooks in einer eigenen — ein Webhook ist dasselbe Objekt unter einem Namen statt unter einer URL, wird also über dieselbe Seite gerendert und sagt, was er ist.

#Versionierung

Pro Version. Eine API-Beschreibung gehört zu dem Release, das sie beschreibt: v1 und v2 haben verschiedene Endpoints, und einem Leser auf v1, der fragt was ein Feld bedeutet, darf nicht die Antwort von v2 gezeigt werden. Jede Versions-Collection trägt das Dokument an ihrem eigenen Ref, und der Versionsumschalter arbeitet auf der Referenz genau wie auf der Prosa.

Das ist das Gegenteil dessen, was der Typ changelog tut, und der Grund, warum Versionierung eine Politik des Typs ist und keine Regel des Layers.

#Lokalisierung

Pro Locale, wo eine Locale ein eigenes Dokument mitbringt. Eine Beschreibung ist genauso geschriebene Prosa wie Struktur — Zusammenfassungen, Feldbeschreibungen, Bedeutungen von Antworten — eine übersetzte ist also ein echtes Artefakt und nicht dieselbe Datei mit anderem Etikett.

{
  type: 'openapi',
  path: 'openapi.yaml',
  label: 'API',
  locales: { de: 'openapi.de.yaml' }
}

Eine Locale, die in der Map fehlt, baut keine Collection, und die bestehende Fallback-Kette liefert ihr die Referenz der Standardsprache, mit dem Übersetzungsbanner als Hinweis — siehe Lokalisierung. Übersetzt bleiben in jedem Fall die Labels des Layers selbst — die Tabellenköpfe, „Request", „Response", die Statusnamen — denn die gehören zum Theme und nicht zum Dokument.

#Wenn das Dokument nicht gelesen werden kann

Der Build schlägt fehl und sagt, welche Sektion und warum. Das ist Absicht: Eine Referenz, die still zu einer leeren Sektion geworden ist, ist eine Referenz, deren Verschwinden niemand bemerkt.