API Dokumentation erstellen und hosten mit Bruno

Wenn Sie Bruno nutzen, kennen Sie den Vorteil: Ihre Sammlungen liegen als einfache .bru-Dateien im Git-Repository, versionskontrolliert neben dem Code und ohne Cloud-Konto. Das ist ein sauberer Offline-First-Ansatz für API-Clients, bei denen Sie die Kontrolle über Ihre Daten behalten.

Apidog heute ausprobieren

Früher oder später kommt aber die Frage: „Wo ist die Dokumentation? Können Sie mir einen Link schicken?“ Genau hier wird Bruno schwierig. Bruno eignet sich gut zum Senden und Versionieren von Requests, aber nicht zum Veröffentlichen eines teilbaren Dokumentationsportals. Dieser Leitfaden zeigt, was Bruno für API-Dokumentation leisten kann, wo die Grenzen liegen und wie Sie aus einer Spezifikation veröffentlichbare Dokumentation generieren.

Was API-Dokumentation praktisch leisten muss

Bevor Sie ein Tool auswählen, definieren Sie das Ziel. Für Entwicklerteams muss API-Dokumentation meist drei Anforderungen erfüllen:

• Teilbare URL: Frontend-Teams, QA, Partner oder externe Entwickler sollen die Dokumentation öffnen können, ohne ein Repository zu klonen oder einen Client zu installieren.
• Synchronität mit der API: Die Dokumentation muss der tatsächlichen API-Spezifikation folgen. Veraltete Dokumentation ist schlimmer als keine Dokumentation.
• Interaktive Requests: Nutzer sollen dokumentierte Endpunkte direkt ausprobieren können, inklusive Parametern, Headers, Authentifizierung und Beispiel-Payloads.

Wenn alle drei Punkte erfüllt sind, wird Dokumentation zur belastbaren Referenz. Fehlt einer davon, landen Rückfragen wieder direkt beim API-Team.

Was Bruno für Dokumentation bietet

Bruno macht einige Dinge richtig:

• .bru-Dateien sind Klartext.
• Requests liegen im Repository.
• Änderungen können über Pull Requests geprüft werden.
• Pro Request können Sie einen docs-Block und Markdown-Notizen pflegen.
• Die Dokumentation ist innerhalb der Bruno-App sichtbar.

Für ein internes Team, das ohnehin im Repository arbeitet, kann das ausreichend sein. Ein Entwickler kann eine .bru-Datei öffnen und Methode, URL, Header, Body und begleitende Hinweise nachvollziehen.

Beispielhaft kann eine Request-Datei Informationen wie diese enthalten:

meta {
  name: Create user
  type: http
}

post {
  url: {{baseUrl}}/users
  body: json
}

headers {
  Content-Type: application/json
}

body:json {
  {
    "email": "[e-mail]",
    "name": "Max Mustermann"
  }
}

docs {
  Erstellt einen neuen Benutzer.
  Erfordert einen gültigen API-Key im Authorization-Header.
}

Das Problem: Diese Dokumentation ist nicht automatisch ein öffentliches oder teilbares Dokumentationsportal.

Wo Bruno an seine Grenzen stößt

Bruno hat kein integriertes, gehostetes, automatisch generiertes öffentliches Dokumentationsportal.

Das bedeutet konkret:

• Es gibt keinen einfachen „Veröffentlichen“-Button für eine Dokumentationsseite.
• Es gibt keine stabile gehostete URL für externe Nutzer.
• Die In-App-Dokumentation ist nur für Personen hilfreich, die Bruno installiert und die Sammlung geklont haben.
• Eine benutzerdefinierte Domain wie docs.example.com ist nicht Teil des Bruno-Dokumentationsflows.
• Interaktive öffentliche Dokumentation muss außerhalb von Bruno umgesetzt werden.

Teams improvisieren deshalb häufig:

1. Bruno-Sammlung oder OpenAPI-Datei exportieren.
2. Separaten Static-Site-Generator verwenden.
3. Dokumentationsseite in CI bauen.
4. Hosting konfigurieren.
5. Änderungen regelmäßig synchron halten.

Das funktioniert, erzeugt aber eine zusätzliche Pipeline und damit einen weiteren Ort, an dem Informationen veralten können.

Besserer Ansatz: Dokumentation aus der Spezifikation generieren

Ein stabilerer Workflow ist: Dokumentation nicht separat schreiben, sondern aus der API-Spezifikation generieren.

In einem Docs-as-Code-Workflow wird die API einmal in einer maschinenlesbaren Spezifikation beschrieben, typischerweise OpenAPI. Diese Spezifikation liegt in Git, wird in Pull Requests geprüft und dient als Vertrag.

Aus dieser Spezifikation können dann generiert werden:

• API-Dokumentation
• Mock-Server
• Tests
• Client-SDKs
• Beispiel-Requests

Der Vorteil: Es gibt keine separate Aufgabe „Dokumentation aktualisieren“. Wenn die Spezifikation korrekt ist, kann die Dokumentation daraus abgeleitet werden.

Dokumentation mit Apidog aus OpenAPI veröffentlichen

Diese Lücke schließt Apidog: Sie behalten ein spezifikationszentriertes Modell bei und generieren daraus eine interaktive, gehostete Dokumentationsseite.

Der Workflow ist:

1. OpenAPI-Spezifikation importieren oder erstellen.
2. Endpunkte, Schemas und Beispiele prüfen.
3. Dokumentationseinstellungen konfigurieren.
4. Sichtbarkeit festlegen.
5. Optional eine benutzerdefinierte Domain verbinden.
6. Dokumentation veröffentlichen.
7. Link mit Nutzern teilen.

Das Ergebnis ist eine Dokumentationsseite, die:

• unter einer teilbaren URL verfügbar ist,
• optional auf einer eigenen Domain liegt,
• interaktive „Ausprobieren“-Requests unterstützt,
• aus der Spezifikation generiert wird,
• nicht als separates manuelles Dokument gepflegt werden muss.

Schritt-für-Schritt: Von OpenAPI zur teilbaren URL

Schritt	Aktion	Ergebnis
1	OpenAPI-Spezifikation in Apidog importieren oder erstellen	Endpunkte, Schemas und Beispiele werden übernommen
2	Projekt öffnen und Dokumentationseinstellungen aufrufen	Dokumentation wird aus der Spezifikation vorbereitet
3	Sichtbarkeit konfigurieren	Dokumentation ist öffentlich, privat oder geschützt
4	Optional benutzerdefinierte Domain einrichten	Dokumentation kann z. B. unter docs.example.com liegen
5	Veröffentlichen	Eine gehostete Dokumentationsseite wird erstellt
6	Link teilen	Nutzer können lesen und interaktive Requests ausführen

Wenn Sie bereits eine Bruno-Sammlung verwenden, können Sie diese zuerst in OpenAPI konvertieren und anschließend die Spezifikation importieren. Der entscheidende Punkt: Das Hosting der Dokumentation ist dann kein eigenes Nebenprojekt mehr, sondern Teil des Dokumentationsworkflows.

Beispiel: OpenAPI als Basis für Dokumentation

Eine minimale OpenAPI-Spezifikation kann so aussehen:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

servers:
  - url: https://api.example.com

paths:
  /users:
    post:
      summary: Benutzer erstellen
      description: Erstellt einen neuen Benutzer mit E-Mail-Adresse und Namen.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  example: [e-mail]
                name:
                  type: string
                  example: Max Mustermann
      responses:
        "201":
          description: Benutzer wurde erstellt
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: usr_123
                  email:
                    type: string
                    example: [e-mail]

Aus einer solchen Spezifikation kann ein Dokumentationsportal Endpunkte, Request-Bodies, Response-Schemas und Beispiele ableiten.

Dokumentation synchron halten

Eine Dokumentations-URL ist nur nützlich, wenn sie aktuell bleibt. Der typische Fehler bei manuellen Setups ist:

1. API wird geändert.
2. Code wird ausgeliefert.
3. Dokumentation wird vergessen.

Wenn die Dokumentation aus der Spezifikation generiert wird, verschiebt sich die Pflege an die richtige Stelle: zur API-Spezifikation.

Praktischer Workflow:

API-Änderung
  ↓
OpenAPI-Spezifikation aktualisieren
  ↓
Pull Request prüfen
  ↓
Spezifikation veröffentlichen/importieren
  ↓
Dokumentation aktualisiert sich aus derselben Quelle

Beispiele:

• Wird ein neues Feld im Response-Schema ergänzt, erscheint es in der Dokumentation.
• Wird ein Endpunkt als veraltet markiert, kann die Dokumentation das anzeigen.
• Ändert sich ein Request-Body, basiert die Dokumentation auf dem aktualisierten Schema.

So wird Dokumentationsqualität nicht von manueller Disziplin abhängig, sondern vom Spezifikationsworkflow.

Wann Bruno ausreicht

Bruno kann ausreichen, wenn:

• nur ein internes Entwicklerteam mit der API arbeitet,
• alle Beteiligten Zugriff auf das Repository haben,
• Bruno ohnehin installiert ist,
• Dokumentation hauptsächlich als Request-Kommentar benötigt wird,
• keine öffentliche URL erforderlich ist.

In diesem Fall können .bru-Dateien plus Markdown-Dokumentation innerhalb der App praktikabel sein.

Wann Sie ein gehostetes Dokumentationsportal brauchen

Ein gehostetes Portal ist sinnvoll, wenn:

• externe Entwickler oder Partner die API nutzen,
• Frontend- oder QA-Teams nur einen Link benötigen,
• Dokumentation ohne Tool-Installation zugänglich sein soll,
• interaktive Requests im Browser wichtig sind,
• Dokumentation unter einer stabilen URL oder eigenen Domain liegen soll,
• Dokumentation direkt aus OpenAPI generiert werden soll.

Dann ist ein spezifikationsbasierter Veröffentlichungsworkflow die robustere Lösung.

FAQ

Kann Bruno öffentliche API-Dokumentation generieren und hosten?

Bruno bietet lesbare .bru-Dateien und eine In-App-Markdown-Dokumentationsansicht. Beides kann in Git versioniert und geprüft werden. Bruno enthält aber kein integriertes, gehostetes, automatisch generiertes öffentliches Dokumentationsportal mit teilbarer URL.

Wie bekomme ich eine teilbare Dokumentations-URL für meine API?

Beschreiben Sie Ihre API in OpenAPI und verwenden Sie ein Tool, das daraus gehostete Dokumentation generiert. In Apidog importieren Sie die Spezifikation, konfigurieren Sichtbarkeit und optional eine eigene Domain und veröffentlichen anschließend die Dokumentation.

Muss ich Bruno aufgeben, um Dokumentation zu veröffentlichen?

Nein. Sie können Bruno weiterhin für lokale Requests verwenden und Ihre API-Spezifikation separat als OpenAPI pflegen oder eine bestehende Bruno-Sammlung in OpenAPI konvertieren. Die veröffentlichte Dokumentation basiert dann auf der Spezifikation.

Warum ist OpenAPI für Dokumentation hilfreich?

OpenAPI beschreibt Endpunkte, Parameter, Authentifizierung, Request-Bodies und Responses in einem maschinenlesbaren Format. Dadurch können Dokumentation, Tests und Mocks aus derselben Quelle abgeleitet werden.

Fazit

Bruno ist stark, wenn Sie API-Requests lokal, Git-basiert und ohne Cloud-Abhängigkeit verwalten möchten. Für teilbare, gehostete und interaktive API-Dokumentation reicht das jedoch nicht aus.

Der robuste Weg ist ein spezifikationsbasierter Workflow: API in OpenAPI beschreiben, Spezifikation versionieren und Dokumentation daraus generieren. So erhalten Teams eine stabile URL, interaktive Requests und Dokumentation, die mit der API synchron bleibt.