In einem Apidog-Projekt werden Endpunkte in einer hierarchischen Struktur von Modul → Ordner → Endpunkte verwaltet.
- Module repräsentieren unabhängige OpenAPI-Dateien, die üblicherweise nach Geschäftsdomäne oder Dienst gruppiert sind.
- Ordner organisieren Endpunkte nach Funktion oder Merkmal innerhalb eines Moduls.
- Endpunkte sind die eigentlichen OpenAPI-Spezifikationen oder API-Definitionen.
Das Verständnis dieser Struktur ist entscheidend, um Ihre APIs effizient zu organisieren.
Hier ist ein einfaches Hierarchiebeispiel:
Apidog Projekt
│
├── Modul: Benutzerdienst (nach Geschäftsdomäne oder Dienst aufgeteilt)
│ │
│ ├── Ordner: Benutzerauthentifizierung (Funktionskategorie)
│ │ │
│ │ ├── Endpunkt: POST /login (Anmeldung)
│ │ └── Endpunkt: POST /register (Registrierung)
│ │
│ └── Ordner: Benutzerinformationen
│ │
│ └── Endpunkt: GET /users/{id} (Benutzerinformationen abrufen)
│
└── Modul: Bestelldienst
│
├── Ordner: Bestellverwaltung
│ │
│ ├── Endpunkt: POST /orders (Bestellung erstellen)
│ └── Endpunkt: GET /orders/{id} (Bestelldetails abrufen)
│
└── Ordner: Zahlung
│
└── Endpunkt: POST /payment/submit (Zahlung absenden)Verständnis von Modulen in Apidog
Nachdem Sie die Projekthierarchie verstanden haben, stellt sich die nächste Frage: Braucht jedes Projekt Module? Wann sollten Sie ein neues erstellen?
Wenn Sie ein neues Projekt erstellen, generiert Apidog automatisch ein Standardmodul. Wenn Ihr Projekt nur einen einzigen Backend-Dienst oder eine kleine Anzahl von Endpunkten enthält, ist dieses Standardmodul in der Regel ausreichend. Wenn Sie jedoch mehrere unterschiedliche API-Dienste verwalten müssen, können Sie für jeden ein separates Modul erstellen.
Zum Beispiel kann ein Projekt-Backend Dienste wie Benutzer, Produkt, Bestellung und Logistik umfassen – jeder ist für eine bestimmte Domäne verantwortlich und wird oft unter verschiedenen Dienst-URLs bereitgestellt. In diesem Fall wird empfohlen, für diese Dienste einzelne Module zu erstellen, um deren Endpunkte unabhängig voneinander zu verwalten.
Sie können ein Modul erstellen, indem Sie auf die Schaltfläche + oberhalb der Ordnerstruktur klicken und Modul auswählen.
Einmal erstellt, erscheint es im linken Projektbaum neben anderen, mit eigenem Bereich für Ordner und Endpunkte. Sie können innerhalb jedes Moduls Endpunkte und Ordner frei hinzufügen.
Module sind voneinander unabhängig, jedes mit eigenen Endpunkten, Schemas, Komponenten und Modulvariablen. Schemas können jedoch modulübergreifend referenziert werden. Darüber hinaus sind projektweite Einstellungen wie Umgebungsvariablen, Datenbankverbindungen und gemeinsame Skripte für alle Module zugänglich.
Jedes Modul entspricht einer vollständigen OpenAPI-Spezifikationsdatei. Beim Exportieren Ihres Projekts werden die OpenAPI-Dateien pro Modul generiert.
Verständnis von Ordnern innerhalb eines Moduls
Nachdem Sie Ihre Module erstellt haben, besteht der nächste Schritt darin, zu planen, wie die Endpunkte darin strukturiert werden sollen.
Jedes Modul beginnt mit einem **Stammordner**, der alle Unterordner und Endpunkte enthält.
Sie können Ordner direkt unter dem Stammordner erstellen oder sie in andere bestehende Ordner verschachteln.
Beim Entwurf der Ordnerstruktur sollten Sie die Komplexität des Moduls berücksichtigen. Für ein Modul mit nur wenigen Endpunkten ist ein einfacher einstufiger Ordner, der nach Funktionen organisiert ist, in der Regel ausreichend. Bei komplexeren Modulen ist es jedoch besser, gut strukturierte, mehrstufige Ordner zu erstellen, um alles organisiert und leicht navigierbar zu halten.
Zum Beispiel könnten Sie in einem Benutzerdienst-Modul Top-Level-Ordner haben wie:
- Benutzerauthentifizierung (für Endpunkte zur Anmeldung, Registrierung, Passwortzurücksetzung)
- Benutzerinformationen
- Zugriffskontrolle
Wenn ein Ordner zu groß oder logisch unabhängig wird, können Sie ihn in ein eigenständiges Modul umwandeln.
Klicken Sie auf das ...-Symbol neben dem Ordnernamen und wählen Sie ...Mehr > In ein neues Modul konvertieren. Dies hilft, Ihre Projektstruktur gut organisiert zu halten, wenn sie skaliert.
Umgebungsverwaltung & Konfiguration für ein Modul
Neben strukturierten Endpunkten entspricht jedes Modul typischerweise einer anderen Dienstadresse oder Bereitstellungsumgebung. Diese können Sie einfach in der Umgebungsverwaltung konfigurieren.
In den Einstellungen der Umgebungsverwaltung kann die Basis-URL jedes Moduls separat konfiguriert werden. Zum Beispiel in einer Testumgebung:
- Benutzerdienst →
http://user-service:8001 - Bestelldienst →
http://order-service:8002
Beim Wechsel der Umgebungen aktualisiert Apidog automatisch die Basis-URL jedes Moduls. Wenn Sie beispielsweise von der Entwicklungsumgebung zur Testumgebung wechseln, ändert sich die Basis-URL des Benutzerdienstmoduls von http://localhost:8001 zu http://user-service:8001, und die Basis-URL des Bestelldienstmoduls ändert sich von http://localhost:8002 zu http://order-service:8002.
Umgebungsvariablen werden über alle Module hinweg geteilt und eignen sich am besten zum Speichern von Einstellungen, die sich zwischen Umgebungen unterscheiden. Modulvariablen hingegen sind für jedes Modul einzigartig – zum Beispiel eigene API-Schlüssel oder Token – und können in jedem Endpunkt innerhalb dieses Moduls verwendet werden.
Schemas verwalten und wiederverwenden
Effizientes Schema-Management hilft, Duplikate zu vermeiden und Konsistenz über Module hinweg sicherzustellen.
Jedes Modul hat einen eigenen Bereich für die Schema-Verwaltung, in dem Sie geschäftsbezogene Datenstrukturen definieren und pflegen können. Diese Schemas können innerhalb des Moduls wiederverwendet oder von anderen referenziert werden.
Zum Beispiel definiert das Modul Benutzerdienst benutzerbezogene Schemas. Das Modul Bestelldienst definiert bestellbezogene Schemas. Wenn der Bestelldienst Benutzerinformationen referenzieren muss, kann er einfach das Schema des Benutzerdienstes wiederverwenden – es muss nicht neu erstellt werden.
Von Postman zu Apidog: Importierte Sammlungen & Endpunkte organisieren
Wenn Ihr Team zuvor Postman verwendet hat, können Sie bestehende Sammlungen und Endpunkte einfach nach Apidog migrieren.
Beim Import:
- Jede Postman-Sammlung wird zu einem Modul.
- Ordnerstrukturen werden automatisch abgebildet.
- Endpunkte und Schemas bleiben erhalten.
So können Sie Ihre vertraute API-Struktur beibehalten und gleichzeitig die Vorteile des modularen Systems von Apidog nutzen.
Fazit
Durch die Definition klarer **Module**, die Organisation von **Ordnern** und die Wiederverwendung von **Schemas** können Sie Ihre Apidog-Projekte sauber, skalierbar und einfach kollaborativ gestalten.
Das modulare Design von Apidog hilft Teams, schneller zu arbeiten, Verwirrung zu vermeiden und komplexe APIs effizienter zu verwalten – vom Design über die Dokumentation bis zum Testen.