Um die API einfach zu verstehen, zu implementieren und zu pflegen, ist eine qualitativ hochwertige Dokumentation wichtig. Wir konfigurieren die automatische Generierung von Dokumentation basierend auf OpenAPI-Spezifikationen mit Swagger UI und Redoc, zwei der beliebtesten API-Visualisierungstools.
Auf diese Weise können Sie Entwicklern eine interaktive Oberfläche zur Verfügung stellen, auf der Sie die Struktur der Methoden lernen, Abfragen testen und sich schnell mit Ihrer API verbinden können.
Was in der Dokumentation enthalten ist
| Abteilung | Die Beschreibung |
|---|---|
| Endpoint's und Methoden | Vollständige Liste der Routen, HTTP-Methoden, Parameter, Header |
| Beispiele für Anfragen/Antworten | Skripte für Curl, Postman, JavaScript, Python und andere Sprachen |
| Autorisation | Unterstützung für JWT, OAuth2, API Key direkt von der Schnittstelle |
| Objektdiagramme | Beschreibung von Modellen, verschachtelten Strukturen und Datenanforderungen |
| Fehlercodes | Alle möglichen Zustände mit Erläuterungen |
Die Werkzeuge, die wir verwenden
Swagger UI - interaktive Dokumentation im Browser, testbar
Redoc ist eine lesbare, statische Schnittstelle, ideal für die Veröffentlichung auf der Website
OpenAPI 3. 0/3. 1 - Spezifikationsformat, auf dem alles aufbaut
Automatische Generierung aus Code - Anmerkungen, Beschreibungen, Versionen und Aktualisierungen der Dokumentation automatisch
Export nach JSON/YAML/HTML
Vorteile für Team und Partner
Beschleunigung des Onboarding neuer Entwickler
Weniger Integrationsfehler
Immer aktuelle, codesynchronisierte Dokumentation
Schneller Start der Integration ohne technischen Support
Einfache Veröffentlichung der Dokumentation auf öffentlichen oder privaten Portalen
Wo es besonders wichtig ist
Offene APIs für externe Entwickler
Interne APIs mit aktiver Entwicklung
Plattformen mit B2B-Integrationen und SDKs
Dienstleistungen mit Regelungsbedarf und Validierung von Schemata
Swagger und Redoc sind der API-Dokumentationsstandard der nächsten Generation. Wir werden die Erstellung, Aktualisierung und Veröffentlichung der Dokumentation so konfigurieren, dass jeder Entwickler in wenigen Minuten mit der Integration mit Ihrer API beginnen kann.