Wenn Sie Bruno übernommen haben, kennen Sie bereits den Reiz. Ihre Sammlungen liegen als einfache .bru-Dateien in Ihrem Git-Repository, versionskontrolliert neben dem Code, ohne dass ein Cloud-Konto erforderlich ist. Es ist eine saubere, Offline-First-Antwort auf API-Clients, die Ihre Daten besitzen wollen.
Doch früher oder später stellt jemand eine Frage, die Bruno nicht gut beantwortet: „Wo ist die Dokumentation? Können Sie mir einen Link schicken?“ Genau hier stoßen Teams an ihre Grenzen. Bruno ist darauf ausgelegt, Anfragen zu senden, nicht um ein teilbares Dokumentationsportal zu veröffentlichen. Dieser Leitfaden behandelt die Generierung von Bruno API-Dokumentation ehrlich, was Bruno Ihnen bietet, was nicht, und wie Sie Dokumente aus Ihrer Spezifikation generieren und hosten, wenn Sie eine echte URL an Konsumenten weitergeben müssen.
Was Teams wirklich von API-Dokumentationen benötigen
Bevor man ein Tool beurteilt, hilft es, das Ziel zu definieren. Wenn Leute von „API-Dokumentation“ sprechen, meinen sie normalerweise drei Dinge, die zusammenwirken:
- Eine teilbare URL. Frontend-Entwickler, Partner und QA müssen die Dokumente lesen können, ohne Ihr Repository zu klonen oder einen Client zu installieren. Ein Link in Slack sollte einfach funktionieren.
- Dokumente, die synchron bleiben. Eine Dokumentation, die von der echten API abweicht, ist schlimmer als keine, weil sie Menschen selbstbewusst in die falsche Richtung lenkt. Die Dokumente müssen der Spezifikation folgen.
- Ein interaktives „Ausprobieren“-Erlebnis. Das Lesen von Endpunktbeschreibungen ist in Ordnung; das Senden einer echten Anfrage an den dokumentierten Endpunkt, mit ausgefüllten Authentifizierungs- und Beispiel-Payloads, macht Dokumente zu einer brauchbaren Referenz.
Erfüllen Sie alle drei, und Ihre Dokumente werden zur einzigen Quelle der Wahrheit. Verpassen Sie eines davon, und die Leute werden Sie direkt fragen, was nicht skaliert.
Brunos Dokumentationsgeschichte
Seien wir fair zu Bruno, denn es macht hier einiges gut.
Brunos Sammlungen sind menschenlesbar. Das .bru-Format ist Klartext, sodass ein Ingenieur, der das Repository durchsucht, eine Anfragedatei öffnen und Methode, URL, Header und Body sehen kann. Bruno unterstützt auch einen docs-Block pro Anfrage und eine Markdown-Dokumentationsansicht innerhalb der App, sodass Sie Prosa hinzufügen können, die erklärt, was ein Endpunkt tut. Da alles in Git ist, werden diese Notizen in Pull-Requests wie jede andere Änderung überprüft. Für ein internes Team, das in der Codebasis arbeitet, ist das eine legitime Form der Dokumentation.
Die ehrliche Lücke ist die Veröffentlichung. Bruno verfügt über kein integriertes, gehostetes, automatisch generiertes öffentliches Dokumentationsportal. Es gibt keinen „Veröffentlichen“-Button, der Ihre Sammlung in eine Website unter einer stabilen URL mit einer benutzerdefinierten Domain verwandelt. Die In-App-Dokumentationsansicht ist für Personen sichtbar, die Bruno bereits installiert und die Sammlung geklont haben, was genau die Zielgruppe ist, die die Dokumentation am wenigsten benötigt.
Daher improvisieren Teams. Gängige Workarounds umfassen das Exportieren der Sammlung oder einer OpenAPI-Datei und das Einspeisen in einen separaten Generator für statische Dokumente, das Einrichten einer Dokumentationsseite in CI oder das Pflegen einer handgeschriebenen README-Datei, die jemand aus dem Gedächtnis aktualisiert. Dies kann funktionieren, aber es fügt eine Build-Pipeline hinzu, die gewartet werden muss, und einen zweiten Ort, an dem Informationen abweichen können. Die Dokumentation ist kein erstklassiges Ergebnis des Tools mehr, mit dem Sie testen; es ist ein Nebenprojekt.
Das Docs-as-Code-Prinzip
Eine sauberere Denkweise darüber, die Bruno-Nutzer bereits halb glauben: Behandeln Sie Ihre Dokumentation als Produkt Ihrer Spezifikation, nicht als separates Artefakt.
In einem Docs-as-Code-Workflow wird Ihre API einmal in einer maschinenlesbaren Spezifikation beschrieben, typischerweise OpenAPI. Diese Spezifikation lebt in Git, wird in Pull-Requests überprüft und dient als Vertrag. Dokumentation, Mock-Server und Client-SDKs werden alle daraus generiert. Wenn sich der Vertrag ändert, wird die Änderung an einer Stelle überprüft, und alles nachgelagerte folgt.
Der Vorteil ist, dass es keine separate „Dokumente aktualisieren“-Aufgabe gibt, die man vergessen könnte. Die Dokumente sind eine Darstellung der Spezifikation. Wenn die Spezifikation richtig und überprüft ist, sind die Dokumente richtig. Dies ist das Prinzip, auf das Bruno hinweist, indem es Sammlungen in Git behält, aber es bleibt vor dem Veröffentlichungsschritt stehen.
Stattdessen Dokumente aus Ihrer Spezifikation generieren und hosten
Dies ist die Lücke, die Apidog schließen soll. Apidog behält das gleiche spezifikationszentrierte, Git-freundliche Denkmodell bei und fügt dann das hinzu, was Bruno weglässt: Es generiert eine interaktive, gehostete Dokumentationsseite direkt aus Ihrer Spezifikation, ohne dass eine separate Build-Pipeline erforderlich ist.
Richten Sie Apidog auf Ihre OpenAPI-Spezifikation aus, und es erstellt automatisch ein Dokumentationsportal. Das Ergebnis ist:
- Gehostet unter einer teilbaren URL, sodass jeder mit dem Link die Dokumente lesen kann, ohne etwas zu installieren.
- Auf einer benutzerdefinierten Domain montierbar, sodass die Dokumente unter
docs.yourcompany.comleben und zu Ihrer Marke passen können. - Interaktiv, mit einem integrierten „Ausprobieren“-Panel, das echte Anfragen unter Verwendung der dokumentierten Parameter, Header und Authentifizierung sendet.
- Aus der Spezifikation generiert, sodass die Dokumente widerspiegeln, was die API tatsächlich deklariert, anstatt einer handgeschriebenen Kopie, die abweichen kann.
Da dieselbe Spezifikation auch Apidogs Tests und Mocks antreibt, müssen Sie nicht drei Beschreibungen einer API pflegen. Sie beschreiben sie einmal und verwenden sie wieder.
Anleitung: von der Spezifikation zur teilbaren URL
Hier ist die Kurzversion der Veröffentlichung von Dokumenten aus einer OpenAPI-Spezifikation.
| Schritt | Aktion | Ergebnis |
|---|---|---|
| 1 | Importieren oder schreiben Sie Ihre OpenAPI-Spezifikation in Apidog | Endpunkte, Schemata und Beispiele werden automatisch ausgefüllt |
| 2 | Öffnen Sie die Dokumentationseinstellungen des Projekts | Dokumente werden aus der Spezifikation generiert und sind bereit zur Konfiguration |
| 3 | Sichtbarkeit und (optional) eine benutzerdefinierte Domain wählen | Dokumente sind öffentlich, privat oder passwortgeschützt |
| 4 | Veröffentlichen | Eine live gehostete Dokumentationsseite wird unter einer stabilen URL erstellt |
| 5 | Link teilen | Nutzer lesen die Dokumente und führen „Ausprobieren“-Anfragen aus |
Wenn Sie bereits eine Bruno-Sammlung haben, können Sie diese zuerst in OpenAPI konvertieren und dann diese Spezifikation importieren. Von dort aus ist der Veröffentlichungsschritt derselbe. Der Punkt ist, dass das Generieren und Hosten der Dokumente eine Funktion ist, keine Pipeline, die Sie selbst zusammenstellen müssen.
Dokumente synchron halten, wenn sich die Spezifikation ändert
Eine Dokumentations-URL ist nur nützlich, wenn sie genau bleibt. Der Fehlerfall bei improvisierten Setups besteht darin, dass jemand eine Endpunktänderung ausliefert und die Dokumente vergisst.
Wenn Dokumente aus der Spezifikation generiert werden, verringert sich dieses Risiko. Sie bearbeiten die Spezifikation, die Spezifikationsänderung durchläuft eine Überprüfung wie jede andere Codeänderung, und die veröffentlichten Dokumente spiegeln den neuen Zustand wider. Es gibt kein paralleles Dokument, an das man denken müsste. Fügen Sie ein Feld zu einem Antwortschema hinzu, und es erscheint in den Dokumenten; kennzeichnen Sie einen Endpunkt als veraltet, und die Dokumente zeigen dies an. Die Arbeit, die Sie bereits leisten, um den Vertrag korrekt zu halten, ist dieselbe Arbeit, die die Dokumente korrekt hält.
Dies ist der praktische Vorteil des Docs-as-Code-Prinzips: Korrektheit wird zu einem Nebeneffekt eines Workflows, den Sie ohnehin wünschen würden, anstatt einer separaten Aufgabe, die von Disziplin abhängt.
FAQ
Kann Bruno öffentliche API-Dokumentation generieren und hosten?
Bruno bietet lesbare .bru-Sammlungsdateien und eine In-App-Markdown-Dokumentationsansicht, die beide in Git überprüft werden. Es enthält kein integriertes, gehostetes, automatisch generiertes öffentliches Dokumentationsportal mit einer teilbaren URL. Um öffentliche Dokumente von Bruno zu veröffentlichen, exportieren Teams typischerweise eine Spezifikation und führen einen separaten Generator für statische Dokumente aus, was eine zu wartende Pipeline hinzufügt.
Wie erhalte ich eine teilbare Dokumentations-URL von meiner API?
Beschreiben Sie Ihre API in einer OpenAPI-Spezifikation und verwenden Sie dann ein Tool, das gehostete Dokumente daraus generiert. In Apidog importieren Sie die Spezifikation, konfigurieren die Sichtbarkeit, fügen optional eine benutzerdefinierte Domain hinzu und veröffentlichen. Das Ergebnis ist eine Live-Dokumentationsseite unter einer stabilen URL, mit einem interaktiven „Ausprobieren“-Panel, die Sie direkt teilen können.
Muss ich meine Bruno-Sammlungen aufgeben, um Dokumente zu veröffentlichen?
Nein. Sie können eine bestehende Bruno-Sammlung in OpenAPI konvertieren und diese Spezifikation in ein Dokumentationstool importieren. Ihre Endpunkte, Schemata und Beispiele werden übernommen, und Sie behalten die Spezifikation unter Versionskontrolle. Die Migration erfolgt auf der Spezifikationsebene, sodass die Docs-as-Code-Gewohnheiten, die Sie mit Bruno entwickelt haben, weiterhin gelten.