Skip to main content

API-Dokumentation automatisch aus Linear generieren

Erstellen Sie ein Dokumentations-Playbook, synchronisieren Sie es als Linear-Label und ermöglichen Sie allen in Ihrem Team, die Generierung der Dokumentation auszulösen, indem sie ein Ticket labeln.
AuthorCognition
CategoryProjektmanagement
FeaturesIntegrationen, Playbooks
1

Erstellen Sie ein Playbook für die Dokumentation

Beginnen Sie damit, ein Playbook für die Aufgabe zu erstellen, die Sie standardisieren möchten. In diesem Beispiel erstellen wir ein Playbook, das API-Dokumentation generiert, sobald ein Teammitglied ein Ticket mit einem Label kennzeichnet.Gehen Sie zu Settings > Playbooks und klicken Sie auf Create playbook. Geben Sie ihm einen Namen und ein Makro (z. B. !add-docs).Schreiben Sie konkrete, schrittweise Anweisungen. Verweisen Sie auf tatsächliche Dateipfade und Konventionen, damit Devin die Standards Ihres Teams einhält:Je spezifischer Ihr Playbook ist, desto besser wird das Ergebnis. Verweisen Sie auf die tatsächlichen Dokumentvorlagen, Styleguides und Tools Ihres Teams. Weitere Informationen zum Schreiben effektiver Playbooks finden Sie in der Playbook-Dokumentation.
2

Playbook mit Linear synchronisieren

Richte deine Linear-Integration ein, falls du das noch nicht getan hast: Navigiere zu Settings > Integrations > Linear und klicke auf Connect. Wähle die Teams aus, auf die Devin Zugriff haben soll.Sobald die Verbindung hergestellt ist, scrolle zu Synced playbook labels und klicke auf Add playbook. Wähle !add-docs aus der Dropdown-Liste. Dadurch wird automatisch ein Label namens !add-docs in Linear unter der Label-Gruppe Devin Playbooks erstellt.Wenn jetzt jemand dieses Label zu einem Ticket hinzufügt, startet Devin eine Sitzung mit deinem Playbook.
Damit Playbook-Labels automatisch mit Linear synchronisiert werden, muss in deinem Linear-Workspace Manage workspace labels auf All members gesetzt sein (zu finden unter Linears Settings > Security). Wenn das nicht aktiviert ist, musst du die Labels manuell in Linear anlegen.
3

Tickets kennzeichnen und Dokumentation generieren

Wenn ein Teammitglied das Label !add-docs zu einem Ticket wie diesem hinzufügt:
ENG-215: Add POST /api/v2/webhooks endpoint — accepts a URL and event types, validates the URL is reachable, stores the subscription, and returns the webhook ID.
startet Devin automatisch eine Sitzung und folgt eurem Docs-Playbook:
  • Liest das Ticket — übernimmt die Beschreibung des Endpoints, Parameter und verlinkte PRs
  • Findet den Quellcode — findet den Route-Handler, das Request-Validierungsschema und die Response-Typen
  • Generiert Dokumentation — erstellt eine neue Seite in docs/api/ entsprechend eurem bestehenden Format
  • Öffnet eine PR — enthält die neue Dokumentationsseite und die aktualisierte Sidebar
Das funktioniert auch gut für Batch-Operationen — wählt mehrere Tickets mit Cmd+A aus, klickt mit der rechten Maustaste und fügt das Label !add-docs hinzu, um Dokumentation für mehrere Endpoints parallel zu erstellen.
Mit der installierten Linear-Integration hat Devin nativen Zugriff auf die Tools von Linear — euer Playbook kann Devin also anweisen, Ticket-Labels oder -Status basierend auf dem Ergebnis zu aktualisieren. Da Labels andere Automatisierungen auslösen können, könnt ihr Workflows verketten — z. B. könnte nach dem Generieren der Dokumentation ein Docs Ready-Label die technische Redaktion zur Überprüfung benachrichtigen.
4

Erstellen Sie weitere Playbooks für Ihr Team

Dasselbe Muster funktioniert für jede wiederkehrende Aufgabe. Erstelle ein Playbook, synchronisiere es als Label, und dein Team kann es von jedem Ticket aus auslösen. Hier sind einige Ideen:
  • !write-tests — Testabdeckung für das im Ticket beschriebene Feature hinzufügen
  • !refactor — Code entsprechend den Konventionen deines Teams refaktorisieren
  • !security-audit — Code auf Sicherheitslücken prüfen und einen Pull Request (PR) mit Korrekturen eröffnen
  • !migrate — Eine standardisierte Migration ausführen (Upgrade von Abhängigkeiten, Erhöhung der API-Version)
Du kannst auch Automatisierungs-Trigger einrichten, damit Devin mit der Arbeit beginnt, ohne dass jemand ein Label setzen muss. Gehe zu Settings > Integrations > Linear, scrolle zu Automation triggers und konfiguriere einen Trigger, der ausgelöst wird, wenn Tickets in einen bestimmten Status wechseln oder ein bestimmtes Label erhalten.