OpenAPI / Swagger

OpenAPI / Swagger

Ein interaktives Swagger-UI-Widget für eine OpenAPI-/Swagger-Spezifikation, mit derselben ::: name ... :::- Container-Syntax wie jeder Block in Content-Blöcke - das direkte Gegenstück zu GitBooks eigenem OpenAPI-Block. src wird auf dieselbe, relativ zu docs/assets/ aufgelöste Weise interpretiert wie das src von ::: file (siehe Content-Blöcke). Sowohl JSON- als auch YAML-Spezifikationen funktionieren; Swagger UI parst beide vollständig clientseitig - nirgendwo in diesem Modul findet eine serverseitige OpenAPI-Verarbeitung statt. Erfordert, dass bxsites.yamls openapi auf true gesetzt ist - ist das nicht der Fall, wird dieser Platzhalter zwar gerendert, bleibt aber inaktiv (Swagger UIs eigenes JS/CSS wird dann überhaupt nicht nach site/ kopiert, sodass der Build jedes anderen Projekts genauso klein bleibt wie vor diesem Feature):

::: openapi src="assets/openapi/example.yaml" title="Bookshelf API"
:::

Das Widget oben ist genau diese Seite, live, und rendert die kleine Beispielspezifikation, die dieser Guide unter docs/assets/openapi/example.yaml mitliefert - öffne sie im eigenen Projekt unter docs/assets/ (oder richte src auf die bereits vorhandene eigene Spezifikation), um dasselbe mit der eigenen API zu sehen.

Vendort ist nur SwaggerUIBundles eigenes Basis-Layout - keine Topbar/"Explore"-Leiste, über die eine andere Spezifikation eingetippt werden könnte (ein ::: openapi-Block soll immer genau die eine Spezifikation zeigen, auf die seine Autorin ihn gerichtet hat), sodass jede Operation samt ihrer Request-/Response-Schemas und "Try it out" (das die eigene servers[0].url der Spezifikation direkt aus dem Browser der Besucherin aufruft - dort muss CORS für den Docs-Host erlaubt sein) direkt aus der bestehenden Spezifikation gerendert wird, ohne dass etwas umgeschrieben werden muss.

Eine einzelne Operation inline

Füge operation="METHOD /path" hinzu, um genau diesen einen Endpunkt in eine gewöhnliche Seite einzubetten - praktisch mitten in einem Tutorial, ohne die Leserin erst zur vollständigen Referenz zu schicken:

::: openapi src="assets/openapi/example.yaml" operation="GET /books"
:::

Immer noch genau dasselbe Swagger-UI-Widget wie der vollständige Block oben (dieselbe Spezifikation, dasselbe rein clientseitige Rendering - auch operation löst niemals eine OpenAPI-Verarbeitung auf unserer Seite aus); jede andere Operation wird einfach ausgeblendet und diese eine automatisch aufgeklappt, indem Swagger UIs eigenes, bereits gerendertes Markup ausgelesen wird. Die Methode in operation ist Groß-/Kleinschreibung egal; ihr Pfad muss exakt dem eigenen Pfad der Spezifikation entsprechen (samt {param}-Platzhaltern).

Eine API ohne Spezifikationsdatei dokumentieren

::: openapi benötigt immer ein echtes OpenAPI-/Swagger-Dokument unter src - es gibt keine manuelle, spezifikationslose Variante dieses Blocks zum handschriftlichen Beschreiben eines einzelnen Endpunkts. Auch GitBook selbst hat so etwas nicht mehr: Sein eigenes Gegenstück, der "API method"-Block, wurde im Februar 2024 zugunsten des Imports einer echten Spezifikation abgeschafft. Falls noch keine existiert:

• Schreibe nur so viel Spezifikation, wie die aktuelle Seite braucht. Ein einzelner paths-Eintrag mit eigenem, minimalem info/servers (siehe docs/assets/openapi/example.yaml dafür, wie wenig das tatsächlich braucht) liefert bereits das interaktive Widget samt "Try it out" für diesen einen Endpunkt - wächst später zur vollständigen Spezifikation heran, ohne dass sich am Block selbst etwas ändert.
• Oder verzichte ganz auf das Widget und beschreibe den Endpunkt als gewöhnlichen Inhalt - eine Parametertabelle, ein Codeblock-Paar für Anfrage/Antwort (```http/```json), begleitet von einem Stepper, falls das beim Durchgehen hilft. Jeder andere Content-Block und jede Markdown-Erweiterung steht auf jeder Seite zur Verfügung, unabhängig davon, ob openapi überhaupt aktiviert ist.