Komponenten
Die drei MDC-Komponenten, aus denen eine generierte Referenzseite besteht.
Der Typ openapi schreibt gewöhnliche Markdown-Seiten, deren Rumpf aus drei
MDC-Komponenten besteht. Sie sind dokumentiert, weil sie Teil der öffentlichen
Fläche sind — ein Consumer kann jede davon überschreiben — nicht weil eine Seite
von Hand geschrieben werden müsste.
OpenApiOverview
Die Titelseite des Dokuments: info, die Server, die Security-Schemes und die
Liste der Tags mit je einer Anzahl.
| Prop | Typ | Anmerkungen |
|---|---|---|
info | Objekt | title, version, summary, Kontakt |
servers | Array | Jeder Server, den das Dokument deklariert |
security | Objekt | Die eigene Anforderung des Dokuments |
schemes | Array | Die Security-Schemes, nach Namen |
tags | Array | Je mit to, einer Beschreibung, einer Anzahl |
OpenApiOperations
Der Index eines Tags: jede Operation darunter als Zeile, mit Methode, Pfad, Zusammenfassung und ob sie deprecated ist.
| Prop | Typ | Anmerkungen |
|---|---|---|
operations | Array | Methode, Pfad, Art, Zusammenfassung, to |
externalDocs | Objekt | Der eigene Link des Tags, wo er einen hat |
OpenApiOperation
Ein Endpoint: Parameter, Request-Body, Antworten, Callbacks und der Try-it-Client.
| Prop | Typ | Anmerkungen |
|---|---|---|
operation | Objekt | Die kompaktierte Operation |
servers | Array | Für diese Operation aufgelöst |
security | Objekt | Die eigene Anforderung der Operation, oder keine |
securitySchemes | Array | Die Schemes, die diese Anforderungen nennen |
Eine davon überschreiben
Wie bei jeder anderen Komponente des Layers: Eine Datei am gleichen Pfad in der konsumierenden Site gewinnt.
app/components/content/OpenApiOperation.vue
Die Props oben sind der Vertrag. Eine Umbenennung hier ist ein Breaking Change des Layers.
Keine eigene Überschrift
Keine der drei beginnt mit einem <h1>. Die Docs-Shell zeichnet den Kopf —
Breadcrumb, Titel, das Kopier-Control daneben — für jede generierte Seite, deren
Rumpf mit keiner Überschrift beginnt, und eine Referenzseite will genau das:
einen Titel und eine Spur wie jede geschriebene Seite.