Mit dem Apidog IDEA-Plugin oder einigen Swagger-Plugins können Sie ganz einfach API-Dokumentationen aus Code generieren und so das Problem des Schreibens von Dokumenten von Grund auf lösen.
Doch selbst nachdem die Endpunkte geschrieben und die Dokumente generiert wurden, sind Sie vielleicht noch unsicher: Ist das API-Design gut genug? Ist die Dokumentation standardisiert? Gibt es Bereiche, die noch verbessert werden können?
Gerade in der Teamzusammenarbeit möchten Sie, dass Ihre API-Dokumente für Teamkollegen auf den ersten Blick leicht verständlich sind. Die Klarheit der Benennung und die Vollständigkeit der Informationen wirken sich direkt auf deren Erfahrung bei der Nutzung Ihrer APIs aus.
Apidog hat kürzlich mehrere KI-Funktionen eingeführt, die Ihnen helfen, die API-Dokumentation in dieser Phase weiter zu optimieren. Ob Sie bestehende Endpunktdetails verbessern oder vorhandene API-Dokumente von anderswo importieren, KI kann praktische Vorschläge bieten.
Im Folgenden zeigen wir Ihnen, wie Sie KI in Apidog nutzen, um standardisiertere API-Dokumentationen zu erstellen. Bevor wir beginnen, stellen Sie bitte sicher, dass Sie Apidog auf die neueste Version aktualisiert, KI-Funktionen aktiviert und das KI-Modell konfiguriert haben.
Import aus bestehender Dokumentation
Manchmal müssen Sie API-Dokumentationen aus anderen Quellen in Apidog migrieren. Wenn die Dokumente in einem Standardformat vorliegen, unterstützt Apidog nativ mehrere Importmethoden: Sie können Dokumente aus Code über das IDEA-Plugin generieren, OpenAPI/Swagger-Spezifikationen importieren oder von anderen Tools wie Postman migrieren.
In einigen Fällen liegen Ihre Dokumentationen jedoch möglicherweise nicht in diesen Standardformaten vor. Zum Beispiel hat das Team zuvor Endpunkte in Markdown dokumentiert, Feldbeschreibungen in Word organisiert oder Endpunktdefinitionen in Chatprotokollen oder E-Mails gefunden. Die manuelle Eingabe jedes Feldes aus diesen nicht standardisierten Quellen in Apidog kann entmutigend sein.
In dieser Situation können Sie die Funktion Schema mit KI ändern nutzen, um die Dateneingabe zu erleichtern. Angenommen, Sie haben Markdown-Inhalte wie diese:
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |Kopieren Sie einfach die Parameter und fragen Sie die KI: "Konvertiere diesen Inhalt in Endpunktparameter und stelle sicher, dass Typen und Pflichtfelder identifiziert werden."
Die KI erkennt automatisch Feldnamen, Datentypen, den erforderlichen Status und Beschreibungen und konvertiert dann alles in Apidogs Standard-Schemaformat. Wenn Enums enthalten sind, organisiert die KI diese auch für Sie in die richtigen Enum-Typen.
KI hilft Ihnen, API-Details zu verfeinern
Nach dem Import der grundlegenden Informationen besteht der nächste Schritt darin, die Details zu verfeinern.
Wenn Sie sich bei einem Feldnamen unsicher sind, verwenden Sie die Funktion KI-Namensgebung. Die KI liefert genauere Namensvorschläge entsprechend den Endpunktspezifikationen und den API-Designrichtlinien.
Sie können auch KI verwenden, um die Feldbeschreibungen automatisch zu vervollständigen, um klarere und vollständigere Erklärungen zu erhalten.
Die Generierung von Mock-Daten ist eine weitere Stärke der KI. Oft wissen wir, wofür ein Feld steht, sind uns aber nicht sicher, welche Beispielwerte verwendet werden sollen. Die KI generiert automatisch sinnvolle Beispieldaten basierend auf dem Feldtyp und der Beschreibung.
Vollständigkeitsprüfung der API-Dokumentation: Auslassungen vermeiden
Wenn die Dokumentation nahezu vollständig aussieht, fragen Sie sich vielleicht immer noch, ob wichtige Informationen fehlen. Verwenden Sie an dieser Stelle die Vollständigkeitsprüfung der API-Dokumentation von Apidog, um zu sehen, ob etwas übersehen wurde.
Die KI scannt Ihre vorhandene API-Dokumentation aus mehreren Perspektiven, um fehlende oder unvollständige Informationen zu identifizieren. Anschließend wird ein detaillierter Bericht erstellt, der jedes Prüfelement bewertet und Ihnen hilft, schnell zu erkennen, wo Ihre API-Dokumente verbessert werden müssen.
Der Bericht sagt Ihnen nicht nur, was zu tun ist – er erklärt auch, warum. Sie haben beispielsweise ein erfolgreiches Antwortformat dokumentiert, aber nicht die möglichen Fehlerszenarien; Sie haben grundlegende Feldbeschreibungen, aber es fehlen Nutzungsbeschränkungen oder Formatierungsanforderungen.
Sie können Ihre API-Dokumentation verbessern, indem Sie den im Bericht enthaltenen Vorschlägen folgen.
Endpunkt-Konformitätsprüfung: Konsistenz gewährleisten
Neben der Vollständigkeit muss die API-Dokumentation auch gut standardisiert sein. Innerhalb eines einzelnen Endpunkts sollte die Benennung einem konsistenten Stil folgen, Feldtypen müssen klar und korrekt definiert sein, und Antwortstrukturen sollten logisch sein. Diese Details spielen eine Schlüsselrolle dabei, Ihre Dokumente leicht lesbar und wartbar zu machen.
Die Funktion Endpunkt-Konformitätsprüfung von Apidog untersucht Ihre Dokumentation aus mehreren Blickwinkeln. Wenn beispielsweise einige Felder mit Verben und andere mit Nomen benannt sind, kennzeichnet die KI die Inkonsistenz und empfiehlt einen einheitlichen Benennungsstil.
Es prüft auch, ob Felddefinitionen konsistenten Standards folgen, wie z.B. die Vermeidung von gemischten Schreibweisen, die gleichzeitige Verwendung von Unterstrichen und CamelCase oder inkonsistente Abkürzungen, und bietet dann klare Vorschläge zur Behebung dieser Probleme.
Zusammenfassung
Die Erstellung einer klaren und standardisierten API-Dokumentation ist unerlässlich. Funktionen wie KI-generierte Testfälle hängen von der Qualität Ihrer Dokumente ab – je vollständiger und konsistenter sie sind, desto genauer und nützlicher werden die generierten Testfälle sein.
Sie müssen nicht alle KI-Funktionen auf einmal nutzen oder Ihren aktuellen Workflow komplett überarbeiten.
Dies ist ein schrittweiser Prozess. Sie können damit beginnen, Ihre vorhandene Dokumentation zu importieren und dann nach und nach KI-Funktionen anwenden, um sie zu verbessern und zu verfeinern. Wenn Sie sich bei einem Vorschlag unsicher sind, können Sie die Dinge unverändert lassen und später darauf zurückkommen, wenn Sie mehr Kontext haben.
Mit der Zeit werden Sie ganz natürlich ein besseres Verständnis für API-Dokumentationsstandards entwickeln. KI hilft nicht nur, unmittelbare Probleme zu beheben – sie hilft Ihnen auch, bessere Dokumentationsgewohnheiten zu entwickeln.