DocDriven

Was ist DocDriven?

DocDriven ist eine visuelle API-Entwicklungsplattform für Frontend-, Backend-, Produkt- und Design-Teams, die von dem dänischen Unternehmen Nordicode ApS betrieben wird. Sie bündelt Interface-Entwicklung, Dokumentation, Mock-Services, Reviews, Änderungshistorien sowie künstliche Intelligenz-basierte Codegenerierung in einem gemeinsamen Arbeitsbereich.

Unter „Design“ wird hier die Gestaltung von Endpunkten, Anfragen, Antworten sowie Datenschemata verstanden – nicht die Erstellung von Bildern, Logos oder Benutzeroberflächenelementen. Es eignet sich dazu, vor der eigentlichen Entwicklung die API-Vorgaben abzustimmen und so Wartezeiten sowie zerstörerische Änderungen zwischen Frontend und Backend zu reduzieren.

Überblick über die Hauptfunktionen

Visualisierung der API-Design

Das Team kann in der Benutzeroberfläche Endpunkte, Methoden, Parameter, Anfragekörper, Antworten sowie Datenschemata erstellen, wodurch Strukturfehler bei der direkten Bearbeitung von YAML vermieden werden. Automatische Vervollständigung und Vorschläge auf der Grundlage bereits vorhandener Eigenschaften helfen dabei, die Benennungen mit dem Schema in Einklang zu halten.

• Backend-Entwickler können vor dem Programmieren Ressourcen, Fehlermodelle und Versionierungsstrategien festlegen.
• Frontend-Entwickler können im Voraus die für die Seite erforderlichen Felder sowie die Interaktionsabläufe festlegen.
• Der Produktmanager kann den Fortschritt der Schnittstellen, die Verantwortlichen sowie ungelöste Probleme einsehen.
• UI-Designer können überprüfen, ob die für die Benutzeroberfläche benötigten Daten bereits im Vertrag enthalten sind.
• Außenstehende Besucher können an der Bewertung bestimmter Projekte teilnehmen, ohne über Berechtigungen für den gesamten Arbeitsbereich zu verfügen.

Visuelle Bearbeitung kann die API-Verwaltung nicht ersetzen. Das Team muss weiterhin Regeln für Authentifizierung, Autorisierung, Idempotenz, Paginierung, Fehlercodes, Geschwindigkeitsbeschränkungen und Kompatibilität festlegen.

OpenAPI-Import und einheitliche Dokumentation

Neue Projekte können entweder von Grund auf erstellt werden oder es ist möglich, bestehende OpenAPI-Spezifikationen zu importieren. Auf diese Weise können die verstreuten internen und externen Schnittstellen in einem einheitlichen Arbeitsraum zusammengefasst werden – als Vertrag, den Frontend-, Backend-Entwickler sowie alle Beteiligten gemeinsam einsehen können.

1. Erstellen Sie Arbeitsbereiche und Projekte oder wählen Sie die Importierung von bestehenden Spezifikationen aus.
2. Überprüfen Sie, ob Endpunkte, Schemata, Beispiele und Sicherheitsdefinitionen vollständig importiert wurden.
3. Erläuterungen zu zusätzlichen Dienstleistungen, Fehlreaktionen und Grenzbedingungen.
4. Mitglieder oder externe Besucher werden zur Bewertung eingeladen, und zu bearbeitende Probleme werden zugewiesen.
5. Veröffentlichen Sie die bestätigte API-Version, um eine Änderungsgrundlinie zu schaffen.
6. Lassen Sie die Frontend-Schicht mit einem Mock Server verbunden sein, während die Backend-Schicht gemäß dem Vertrag implementiert wird.

Eine erfolgreiche Importierung bedeutet nicht, dass die semantischen Regeln vollständig korrekt sind. Zyklische Verweise, benutzerdefinierte Erweiterungen, Sicherheitsmechanismen sowie komplexe polymorphe Modelle müssen separat getestet werden.

Wie man einen Mock Server verwendet

DocDriven kann auf der Grundlage der API-Struktur sofortige Cloud-Mock-Server erstellen, sodass die Aufrufer Anfragen und Antworten testen können, noch bevor der eigentliche Backend fertiggestellt ist. Frontend-, Mobile- sowie Automatisierungs tests können parallel unter Verwendung desselben Vertrags durchgeführt werden.

• Als Reaktion darauf werden Beispiele für repräsentativen Erfolg, fehlgeschlagene Überprüfungen, unbefugten Zugriff sowie Serverfehler definiert.
• Schreiben Sie keine Produktkeys, echte persönliche Informationen oder Kundendaten in die Beispiele.
• Überprüfen Sie, ob der Statuscode, die Header sowie die Verzögerung der Mock-Antwort die Client-Logik abdecken.
• Nach dem Go-Live der Backend-Schicht werden Vertragstests verwendet, um die tatsächliche Umsetzung mit der Konzeption zu vergleichen.

Ein Mock-Server ist lediglich ein Simulationsdienst und garantiert nicht, dass die Leistung, Sicherheit, Transaktionsfähigkeit sowie Datenkonsistenz des echten Backends den Anforderungen entsprechen.

Echtzeit-Kollaboration und Verantwortungsbewaltung

Teammitglieder können Planänderungen einsehen, Kommentare zu den Konzepten abgeben, Probleme melden und Verantwortliche festlegen. Projektbesucher können nur die eingeladenen Projekte aufrufen und nicht auf andere Projekte oder Einstellungen der Arbeitsbereiche zugreifen.

Die Bewertungsprotokolle sollten die Gründe für die Entscheidung, die Auswirkungen auf die Kompatibilität sowie den Migrationsplan darlegen – anstatt lediglich einen Abschlussvermerk zu machen. Bei Verwendung von öffentlichen oder Partner-APIs sollten zudem formelle Genehmigungs- und Veröffentlichungsprozesse eingeführt werden.

Changelog und Baseline

Die Baseline erfasst den Zustand der API zu einem bestimmten Zeitpunkt und vergleicht ihn mit späteren Designs. Die Unterschiede werden nach hinzugefügten, entfernten oder geänderten Endpunkten oder Schemata kategorisiert, um dem Team dabei zu helfen, mögliche Veränderungen, die den Client beeinträchtigen könnten, frühzeitig zu erkennen.

• Erfassen Sie vor der stabilen Veröffentlichung eine klare Baseline.
• Überprüfen Sie Löschungen von Feldern, Änderungen der Typen, die Pflichtstatus sowie Veränderungen in der Anfragestruktur.
• Legen Sie neue Versionen und Fristen für die Migration fest, um zerstörerische Änderungen vorzunehmen.
• Fügen Sie im Changelog den Geschäftskontext, das Veröffentlichungsdatum und die Aktualisierungen hinzu.
• Die Differenzprüfung in den Pull-Request- oder Veröffentlichungsprozess einbeziehen.

Automatische Unterschiede können Strukturveränderungen erkennen, verstehen aber nicht unbedingt die geschäftliche Semantik. Änderungen an der Bedeutung von Feldern, Standardwerten oder Berechtigungen können auch dann den Aufrufer beeinflussen, wenn sich das Schema nicht ändert.

AI Code Assistant

Code Assistant bezieht sich auf die Beispieldateien sowie die Teamkonfigurationen in den GitHub-Repositorien, um Code für die Endpunkte oder Schemata in DocDriven zu erzeugen. Sein Ziel ist es, Vorlagen nach den bestehenden Konventionen zu erstellen, anstatt die gesamte Geschäftslogik eigenständig zu entwickeln.

Anforderungen an die Konfigurationsdatei

Der Wurzelverzeichnis des Speichers benötigt ein docdriven.config.json. Jedes Template enthält einen Namen, Beispielfehler, das Ausgabeverzeichnis sowie den Zieltyp. Der Zieltyp kann Entpoints oder Schemas sein; die Beispielfehler dienen dazu, die Struktur und den Stil der generierten Code zu bestimmen.

Ausgabemethode

• Erstellen Sie einen Pull Request, der von den Entwicklern überprüft und anschließend integriert werden kann.
• Einsenden an die aktuell ausgewählte Branch.
• Einreichen in andere Branches oder andere autorisierte Repositorien.
• Auf der Protokollseite können Sie den Erstellungsprozess, Fehlschläge und den Abschlusszustand einsehen.

Bevorzugen Sie Pull Requests und lassen Sie Tests, statische Analyse sowie manuelle Überprüfungen gemeinsam sicherstellen. Der generierte Code kann Fehler enthalten, übermäßige Berechtigungen, unsichere Handhabung von Eingaben oder eine Implementierung, die nicht mit den Geschäftsregeln übereinstimmt.

GitHub-Verbindung und Sicherheit

Um Code Assistant verwenden zu können, ist eine Autorisierung über GitHub erforderlich, damit DocDriven auf die Repositorien zugreifen, Codebeispiele lesen und generierte Inhalte hochladen kann. Der Umfang der Autorisierung hat einen direkten Einfluss auf den Schutz von privatem Code sowie auf die Sicherheit der Lieferkette.

• Genehmigungen werden nur an die Organisationen und Lagerhäuser erteilt, die sie tatsächlich benötigen.
• Verwenden Sie spezielle Branches, geschützte Hauptbranches sowie eine verpflichtende Überprüfung von Pull Requests.
• Legen Sie Schlüssel nicht in Beispieldateien, Konfigurationen oder Protokollen ab.
• Überprüfen Sie regelmäßig die Berechtigungen der GitHub-Anwendung und deaktivieren Sie Verbindungen, die nicht mehr benötigt werden.
• Prüfung auf Abhängigkeiten, die Sicherheitslücken, Lizenzen und bösartige Pakete verursachen.
• Die Zugriffsrechte werden umgehend zurückgenommen, wenn der Mitarbeiter kündigt, das Projekt beendet wird oder die Probezeit endet.

Preise und Pakete

Eine Probephase erfordert keine Kreditkarte. Nach Ablauf muss ein Zahlungsplan gewählt werden, andernfalls wird das Konto gesperrt, bis entweder ein Abonnement abgeschlossen oder das Konto geschlossen wird. Die angezeigten Preise für Teams können von der Monats- oder Jahreszahlung, Steuern sowie dem Standort abhängen. Mindestens drei Plätze bedeuten, dass die Kosten für ein Team höher sind als der Preis pro Platz.

Der Aufstieg wird proportional zum aktuellen Abrechnungszeitraum berechnet, der Abstieg tritt im nächsten Abrechnungszeitraum in Kraft. Auf der offiziellen Seite werden keine klaren Regeln für Rückerstattungen angegeben; vor der Zahlung sollten Verlängerung, Stornierung, nicht genutzte Zeitperioden sowie die Handhabung von Steuern überprüft werden.

Privatsphäre und Datenverarbeitung

Der in der Datenschutzerklärung genannte Betreiber ist Nordicode ApS; das Update erfolgte im Dezember 2023. Die Plattform verarbeitet Namen, E-Mail-Adressen, Kontodaten sowie Informationen zu Zahlungen und Nutzung. Die Zahlungsdaten werden von Stripe verarbeitet. Laut den Dienstbedingungen wird das System in Deutschland gehostet.

• Dienste können Kontoinformationen zur Authentifizierung, Lieferung, Kommunikation, Sicherheit und Verbesserung nutzen.
• Die Nutzer können gemäß den geltenden Gesetzen die Ansicht, Aktualisierung oder Löschung ihrer persönlichen Daten beantragen.
• Die Plattform gibt an, organisatorische und technische Maßnahmen zu ergreifen, garantiert jedoch nicht, dass alle Risiken beseitigt werden können.
• Die Dienste sind nicht gemäß branchenspezifischen Vorschriften wie HIPAA oder FISMA konzipiert; die Aufsichtsbehörden sollten vorsichtig sein.
• GitHub-Repositorys, API-Designs und generierter Code können Geschäftsgeheimnisse enthalten; daher sollte zunächst eine Prüfung durch den Lieferanten durchgeführt werden.

Auf der Datenschutzseite wird nicht ausreichend erklärt, welche Anbieter von Modellen der AI Code Assistant verwendet werden, wie lange die Codes aufbewahrt werden und zu welchen Zwecken sie trainiert werden. Vor dem Zugriff auf private Repositorien sollte man mit dem Verkäufer die Vereinbarungen bezüglich der Datenverarbeitung, der Unterverarbeiter sowie die Richtlinien zur Löschung von Backups und zu den Modelldaten klären.

Bedingungen, Urheberrechte und kommerzielle Beschränkungen

Die Bedingungen erlauben die Nutzung der Dienste zu internen Geschäftszielen, sofern dies den Vorschriften entspricht, und behalten das Recht am Plattformcode, an Datenbanken, am Design sowie an der Marke für sich. Die Plattform ist keine Open-Source-Codebasis, und ein kostenpflichtiges Abonnement bedeutet nicht, dass die Dienste kopiert oder weiterverkauft werden dürfen.

• Der Benutzer muss sicherstellen, dass die hochgeladenen APIs, Code und Inhalte über die notwendigen Rechte verfügen.
• Direkt eingereichte Vorschläge können gemäß den Bestimmungen an den Betreiber übertragen werden; vor dem Senden vertraulicher Ideen sollte dies geprüft werden.
• Offene Beiträge können eine breite Palette an Nutzungsrechten gewähren; private Entwürfe sollten nicht in öffentliche Bereiche aufgenommen werden.
• Die Dienste können sich ändern, unterbrochen werden oder eingestellt werden; das Team muss die wichtigen Vorgaben exportieren und eigene Backups anlegen.
• Die Bestimmungen unterliegen dem dänischen Recht; Unternehmen mit Niederlassungen in verschiedenen Ländern müssen die Vertrags- und Datensicherheitspflichten bewerten.

Plattformen, APIs und Open-Source-Status

Passend für Nutzer und Szenarien

• Backend-Team: Vereinheitlichen vor der Implementierung Ressourcen, Schemata, Fehler- und Versionsregeln.
• Frontend- und Mobile-Team: Entwicklung und Überprüfung der Benutzeroberfläche mit einem Mock Server im Voraus.
• Produktmanager: Überwachung des APIs-Plans, Prüfung von Problemen und Ansprechpartner.
• Plattform-Entwicklerteam: Aufrechterhaltung der Konvergenz mehrerer interner und externer APIs.
• Technischer Leiter: Überprüfung der Baseline-Unterschiede und Kontrolle zerstörerischer Änderungen.
• Teams, die GitHub verwenden: Erstellen Sie eine überprüfbare Vorlageimplementation gemäß dem vorhandenen Code-Stil.

Vorteile und Grenzen der Fähigkeiten

Hauptvorteile

• API-Design, Mocking, Zusammenarbeit, Änderungsverfolgung und Codegenerierung in einem einzigen Workflow zusammenfassen.
• Die visuelle Bearbeitung senkt die Hürden für Personen ohne Backend-Kenntnisse, an der Überprüfung von Schnittstellen mitzuwirken.
• Baseline macht die Unterschiede zwischen Endpunkten und Schema übersichtlicher.
• Code Assistant gibt Beispiele für Repositorien sowie Ausgabeformate für Konfigurationsbeschränkungen an.
• 30 Tage voll funktionsfähige Testversion zur Überprüfung in echten Teams.

Hauptbeschränkungen

• Von KI erzeugter Code muss weiterhin überprüft, getestet und auf Sicherheit hin geprüft werden.
• Ein Team-Plan mit mindestens drei Plätzen eignet sich nicht für Personen, die nur ein Konto benötigen.
• Ein Mock-Server kann echte Backend-Tests nicht ersetzen.
• Der Anbieter des unveröffentlichten Modells, die Details zur Codeverarbeitung, die Plattform-APIs sowie der Quellcode sind nicht öffentlich.
• Der Service ist nicht für spezielle, streng regulierte Rahmenbedingungen konzipiert.
• Das Dokument wird weiterhin als in Entwicklung markiert; einige Grenzen müssen bei der Support-Abteilung bestätigt werden.

Häufige Fragen

Ist DocDriven ein Tool für die Benutzeroberflächenentwicklung?

Nein. Es ist dafür konzipiert, API-Endpunkte, Anfragen, Antworten sowie Datenmodelle zu definieren und dabei zu helfen, dass Frontend und Backend gemäß dem Interface-Vertrag zusammenarbeiten.

Ist für die Probephase eine Kreditkarte erforderlich?

Nicht notwendig. Die 30-tägige Testversion bietet einen einzigen Arbeitsbereich sowie alle Funktionen. Nach Ablauf der Zeit wird das Konto ohne Zahlung suspendiert.

Wie viele Personen sind im Team mindestens erforderlich?

Die aktuelle Seite sieht vor, dass mindestens 3 bezahlte Nutzer erforderlich sind; außerdem können unbegrenzt viele Besucher eingeladen werden. Der endgültige Preis muss auf der Zahlelseite bestätigt werden.

Kann man bestehende OpenAPIs importieren?

Projekte können aus den vorhandenen OpenAPI-Spezifikationen erstellt werden. Nach dem Import müssen die benutzerdefinierten Erweiterungen, Sicherheitsdefinitionen sowie komplexe Modelle überprüft werden.

Kann ein Mock-Server als Produktiv-Backend dienen?

Nicht möglich. Es wird zur Simulation von Designs, zur parallelen Entwicklung der Frontend-Teile sowie zum Vertragstesting verwendet. Es verfügt nicht über Logik für die Produktionsabläufe und keine Garantien bezüglich der Daten.

Wird die KI direkt den Hauptzweig ändern?

Die Ausgabemethode kann auf Pull Request, die aktuelle Branch oder eine andere Branch im Repository konfiguriert werden. Das Produktionsteam sollte geschützte Branches sowie eine obligatorische Überprüfung verwenden.

Wird der generierte Code den Teamrichtlinien entsprechen?

Code Assistant bezieht sich auf Konfigurationsdateien und Beispielcode, kann aber dennoch von den Regeln abweichen. Es müssen Formatierungen durchgeführt, Tests durchgeführt sowie eine manuelle Überprüfung vorgenommen werden.

Ist DocDriven Open Source?

Es handelt sich nicht um ein verifizierbares Open-Source-Produkt. Die Unterstützung für OpenAPI und GitHub-Integration bedeutet nicht, dass der Quellcode der Plattform öffentlich zugänglich ist.

Gibt es eine öffentliche API für die Plattform?

Derzeit gibt es keine DocDriven API oder SDK für normale Entwickler. Bei Bedarf an Automatisierung sollte man sich zunächst mit dem Produktteam in Verbindung setzen.

Eignet es sich für medizinische oder streng regulierte Daten?

Die Bestimmungen legen klar fest, dass der Service nicht für spezielle Vorschriften bestimmter Branchen entwickelt wurde. Im Falle von regulierten Schnittstellen oder Code muss eine Konformitäts- und Vertragsprüfung durchgeführt werden, bevor eine Anbindung vorgenommen wird.

Zusammenfassung

DocDriven eignet sich für Teams, die vor dem Programmieren gemeinsame API-Verträge festlegen möchten und durch Mocks, Differenzverfolgung sowie AI-gestütztes Mustercode die Zusammenarbeitskosten senken wollen. Vor dem Kauf sollten insbesondere die GitHub-Rechte, die Richtlinien bezüglich der Modelldaten, die Mindestanzahl der Nutzer sowie die Prozesse zur Exportierung von Backups überprüft werden.