Apidog ist eine Plattform für die API-Zusammenarbeit und -Verwaltung, die das Importieren von API-Spezifikationen in vielen Formaten unterstützt. Es kann direkt fast alle gängigen API-Spezifikationsformate importieren, einschließlich OpenAPI/Swagger, Postman Collections, HAR-Dateien und cURL-Befehle.
In vielen realen Projekten besteht die größte Herausforderung jedoch nicht darin, wie man API-Spezifikationen importiert – sondern darin, dass überhaupt keine API-Spezifikationen zum Importieren verfügbar sind. Einige ältere oder Legacy-Systeme haben nie eine API-Dokumentation gepflegt und verfügen nicht über OpenAPI- oder Swagger-Dateien.
In diesen Fällen ist die Verwendung eines Paket-Capture-Tools oft der schnellste Ansatz, wenn Sie fehlende API-Dokumentation schnell wiederherstellen oder Testfälle erstellen müssen, damit Tester mit realen Daten arbeiten können.
Indem Sie den HTTP/HTTPS-Verkehr der Anwendung erfassen, nützliche Anfragen filtern, sie als HAR oder cURL exportieren und dann in Apidog importieren, können Sie schnell API-Dokumentation generieren und die Grundlage für weitere API-Tests legen.
Es gibt viele Tools zur Verkehrsaufzeichnung. Dieser Artikel verwendet Charles Proxy als Beispiel, um die spezifischen Operationen zu demonstrieren, aber Sie können auch Alternativen wie Proxyman, Fiddler oder die in Ihrem Browser integrierten Entwicklertools für die Paketerfassung verwenden. Der Kern-Workflow ist bei all diesen Tools im Wesentlichen derselbe.
Charles Installation und Grundkonfiguration
Charles bietet eine 30-tägige kostenlose Testversion an. Sie können die neueste Version von der offiziellen Website herunterladen und auf Ihrem System installieren.
Wenn Sie Charles zum ersten Mal starten, werden Sie möglicherweise gefragt, ob die Netzwerkeinstellungen automatisch konfiguriert werden sollen. Es wird empfohlen, "Grant Privileges" (Berechtigungen erteilen) auszuwählen, um die erforderlichen Berechtigungen zu erteilen. Dies ermöglicht es Charles, den HTTP-Verkehr Ihres Systems automatisch zu erfassen.
Charles-Stammzertifikat für HTTPS-Erfassung installieren
Um HTTPS-Verkehr zu erfassen, müssen Sie das Stammzertifikat von Charles installieren. Dieser Schritt ist unerlässlich, da die meisten modernen APIs HTTPS verwenden.
Unter macOS:
- Klicken Sie in der Menüleiste auf "Help → SSL Proxying → Install Charles Root Certificate" (Hilfe → SSL-Proxying → Charles-Stammzertifikat installieren)
- Die Anwendung "Schlüsselbundverwaltung" wird automatisch geöffnet
- Suchen und finden Sie das Charles Proxy-Zertifikat
- Doppelklicken Sie darauf und ändern Sie die Vertrauenseinstellung auf "Immer vertrauen"
Unter Windows:
- Klicken Sie in der Menüleiste auf "Help → SSL Proxying → Install Charles Root Certificate" (Hilfe → SSL-Proxying → Charles-Stammzertifikat installieren)
- Installieren Sie das Zertifikat während des Installationsvorgangs im Speicher "Vertrauenswürdige Stammzertifizierungsstellen"
SSL-Proxying aktivieren
Nachdem das Zertifikat installiert wurde, müssen Sie das SSL-Proxying aktivieren:
- Wählen Sie in der Charles-Menüleiste Proxy → SSL Proxying Settings (Proxy → SSL-Proxy-Einstellungen)
- Aktivieren Sie die Option "Enable SSL Proxying" (SSL-Proxying aktivieren)
3. Fügen Sie die Domainnamen (Host) und Ports (Port 443), die Sie erfassen möchten, der Liste hinzu
4. Sie können auch * verwenden, um alle Domains zu überwachen
Nachdem die Konfiguration abgeschlossen ist, kann Charles vollständige HTTP/HTTPS-Anfragen und -Antworten erfassen.
Tipp: Wenn Sie unsicher sind, welche Domains Ihre Anwendung verwendet, können Sie die Anwendung zunächst frei bedienen und dann die Anfragen unter "Encrypted" (Verschlüsselt) in der Charles-Sitzungsliste beobachten. Notieren Sie sich die entsprechenden Domains und fügen Sie diese dann zu den SSL-Proxy-Einstellungen von Charles hinzu.
API-Verkehr Ihrer Anwendung aufzeichnen
Starten Sie die Anwendung oder Webseite, die Sie analysieren möchten, und interagieren Sie mit verschiedenen Funktionen, wie z.B. dem Anmelden, Abfragen von Daten, Absenden von Formularen oder Hochladen von Dateien. Der Sitzungsbaum auf der linken Seite von Charles wird in Echtzeit aktualisiert und gruppiert Anfragen nach Domain und URL.
Wenn Sie eine bestimmte Anfrage auswählen, zeigt das rechte Panel die grundlegenden Informationen und den Antwortinhalt dieser Anfrage an. Im Reiter "Contents" (Inhalte) werden JSON- und andere Antworten in einer Baumstruktur zusammengefasst, was es einfach macht, die Datenstruktur und Felder schnell zu verstehen.
Filtern und Exportieren von API-Endpunkten
Nach Abschluss der Aufzeichnung stellen Sie möglicherweise fest, dass eine große Anzahl von Anfragen erfasst wurde. Neben tatsächlichen API-Aufrufen gibt es verschiedene Anfragen für statische Ressourcen, Aufrufe von Drittanbieterdiensten und anderen Netzwerkverkehr. An diesem Punkt müssen Sie filtern und nur die Endpunkte beibehalten, die für Sie relevant sind.
Filteroptionen
1. Fokus auf bestimmte Domains oder Pfade:
Klicken Sie mit der rechten Maustaste auf eine Domain oder einen Pfad und wählen Sie "Focus" (Fokussieren)
Charles behält nur die Anfragen unter diesem Knoten bei, was Ihre Analyse erleichtert
2. Irrelevante Anfragen entfernen:
Klicken Sie mit der rechten Maustaste auf irrelevante Anfragen und wählen Sie "Clear" (Löschen), um sie zu entfernen
Oder wählen Sie mehrere Anfragen aus und löschen Sie diese gesammelt
3. Cache-Probleme behandeln:
Wenn das Caching dazu führt, dass HTML oder JSON nicht korrekt angezeigt werden, klicken Sie mit der rechten Maustaste und wählen Sie "No Caching" (Kein Caching)
Dadurch ignoriert Charles das Caching bei nachfolgenden Anfragen, sodass Sie den vollständigen Antwortinhalt erfassen können
Als HAR-Datei exportieren
Nachdem die Filterung abgeschlossen ist, exportieren Sie Ihre ausgewählten Sitzungen:
- Wählen Sie die Sitzungen aus, die Sie exportieren möchten:
Sie können einen gesamten Domainknoten auswählen, oder
Halten Sie Cmd (Mac) oder Strg (Windows) gedrückt und wählen Sie einzelne Anfragen individuell aus
Wählen Sie in der Menüleiste File → Export Session (Datei → Sitzung exportieren)
Wählen Sie im Exportdialog das Format "HTTP Archive (.har)" aus, um eine HAR-Datei zu erstellen
Importieren in Apidog zur automatischen Generierung von API-Dokumentation
Jetzt ist es an der Zeit, Ihren erfassten Datenverkehr in Apidog zu importieren:
- Öffnen Sie den Apidog-Client
2. Gehen Sie zu Projekteinstellungen → Daten importieren → .har-Datei
3. Wählen Sie die HAR-Datei aus, die Sie aus Charles exportiert haben
Apidog analysiert automatisch den Dateinhalt und zeigt die erkannten Endpunktinformationen im Vorschaubereich an, einschließlich:
- Die Anzahl der erkannten Endpunkte
- Anfragemethoden (GET, POST, PUT, DELETE usw.)
Während des Importvorgangs können Sie Optionen konfigurieren, wie zum Beispiel:
- In welches Modul importiert werden soll
- Ob bestehende Endpunkte überschrieben werden sollen
Nach Abschluss des Imports können Sie die Endpunkte im entsprechenden Modul anzeigen.
API-Dokumentation verfeinern und optimieren
Automatisch generierte API-Dokumentation ist ein großartiger Ausgangspunkt, erfordert jedoch in der Regel weitere Anpassungen, um Ihren Geschäftsanforderungen gerecht zu werden. Hier sind einige gängige Verbesserungen:
- Endpunktnamen verbessern: Ändern Sie generische Namen in aussagekräftigere
- Parameterbeschreibungen hinzufügen: Dokumentieren Sie, was jeder Parameter tut und wann er verwendet werden soll
- Antwortkomponenten verfeinern: Organisieren Sie Antwortkomponenten passend zu Ihrer Geschäftslogik
- Beispiele hinzufügen: Fügen Sie Beispielanfragen und -antworten hinzu
- Authentifizierung konfigurieren: Wenn ein Endpunkt eine Authentifizierung erfordert, konfigurieren Sie die entsprechenden Informationen in den Umgebungsvariablen oder Auth-Einstellungen von Apidog. Dies stellt sicher, dass Ihre API-Aufrufe beim Testen korrekt funktionieren.
Fazit
Durch die Aufzeichnung von HTTP/HTTPS-Verkehr mit Paket-Capture-Tools und den anschließenden Import in Apidog können Sie schnell API-Dokumentation generieren und eine reale Datenbasis für Tests bereitstellen.
Ob Browser, Desktop-Client oder mobile Anwendung – diese Methode kann den Zeitaufwand für die Erstellung von API-Dokumentation erheblich reduzieren und Ihrem Team einen schnellen Einstieg in API-Tests und -Entwicklung ermöglichen.