Dokumentation zum Generieren von APIs
Das Dokumentieren der API eines Quellcoderepositorys ist unerlässlich, um den Entwicklern, die die API verwalten und nutzen, Klarheit, Zugänglichkeit und Benutzerfreundlichkeit zu bieten. Eine umfassende Dokumentation dient als Anleitung zum Verständnis der Funktionalität, der Eingaben und Ausgaben sowie zur Verwendung der API-Endpunkte. Beim Dokumentieren der API sollten Sie das am besten geeignete Präsentationsformat (z. B. OpenAPI-Spezifikation oder Markdown) auswählen, Beispiele und Verwendungsszenarien einschließen, die Dokumentation mit Codeänderungen auf dem neuesten Stand halten und API-Benutzer um Feedback bitten, um die Qualität der API kontinuierlich zu verbessern.
Obwohl der allgemeine Ansatz für das Dokumentieren einer API plattformunabhängig ist, gibt es hinsichtlich der Implementierung einige Unterschiede zwischen Azure DevOps und GitHub.
Dokumenterstellungs-API in Azure DevOps
Die effizienteste Methode, um einem Azure DevOps-Projekt eine API-Dokumentation hinzuzufügen, ist die Verwendung eines dedizierten Dokumentationstools oder einer Dokumentationsplattform, das bzw. die in Ihren Entwicklungsworkflow integriert werden kann. Beliebte Tools und Plattformen in dieser Kategorie sind Swagger (OpenAPI), API Blueprint und Markdown-basierte Dokumentationssysteme wie MkDocs oder Docusaurus. Diese Tools bieten Funktionen für die Azure DevOps-Integration, mit denen Sie die Generierung der Dokumentation automatisieren und sie mit der Codebasis synchronisieren können. Die meisten Dokumentationstools unterstützen auch die Analyse von Inlinekommentaren und deren Einbeziehung in die automatisch generierte Dokumentation.
Veröffentlichen Sie die API-Dokumentation an einem zentralen Ort, auf den die Teammitglieder und Projektbeteiligten zugreifen können. Sie können z. B. eine dedizierte Dokumentationswebsite, ein Wiki in Azure DevOps oder ein externes Dokumentationsportal verwenden.
Alternativ können Sie direkt in Ihrem Code Codeanmerkungen oder Decorator-Elemente verwenden, um Metadaten hinzuzufügen, die die API-Endpunkte beschreiben. Tools wie Swagger Codegen oder Springfox können diese Anmerkungen verarbeiten und die OpenAPI-Spezifikationsdateien generieren.
Richten Sie automatisierte Prozesse in Azure Pipelines ein, um die API-Dokumentation automatisch zu generieren, wenn eine Änderung an der Codebasis vorgenommen wird. Dadurch wird sichergestellt, dass die Dokumentation immer auf dem neuesten Stand ist und die aktuellen Änderungen Ihrer APIs widerspiegelt.
Dokumentieren einer API in Github
Wenn Sie GitHub verwenden, können Sie ggf. Tools, die Teil des GitHub-Ökosystems sind, zum Generieren der API-Dokumentation nutzen.
Dokumentieren Sie zunächst Ihre API-Endpunkte, Vorgänge, Parameter, Antworten und andere relevante Informationen. Erwägen Sie, die Dokumentation im Markdown-Format zu erstellen, um eine umfassende Unterstützung und Benutzerfreundlichkeit sicherzustellen. Definieren Sie eine konsistente Struktur einzelner Dokumente, und unterteilen Sie diese in Abschnitte, in denen die Authentifizierung, Endpunkte, Anforderungsparameter, Antwortbeispiele usw. beschrieben werden.
Wie bei Azure DevOps können Sie Dokumentationsgeneratoren oder Generatoren für statische Websites verwenden, um den Prozess der Generierung der API-Dokumentation aus Markdown-Dateien zu optimieren. Beliebte Generatoren sind Jekyll, MkDocs, Docusaurus und Hugo. Konfigurieren Sie den Generator, um Markdown-Dateien zu analysieren und statische HTML-Seiten zu generieren. Sie können das Layout, das Design und die Formatierung an das Branding Ihres Projekts und Ihre Vorlieben anpassen.
Um den HTML-Inhalt zu veröffentlichen, nutzen Sie GitHub-Seiten, mit denen Sie statische Websites direkt aus Ihrem GitHub-Repository hosten können. Sie können zu diesem Zweck einen dedizierten Branch erstellen und die HTML-Dateien in diesen Branch pushen. Sie können auch GitHub Actions implementieren, um die API-Dokumentation automatisch zu erstellen und bereitzustellen, wenn eine Änderung an den Dokumentationsdateien oder der Codebasis vorgenommen wird.
Richten Sie GitHub-Aktionen ein, um Ihre API-Dokumentation automatisch zu erstellen und bereitzustellen, wenn eine Änderung an den Dokumentationsdateien oder der Codebasis vorhanden ist. Konfigurieren Sie den Automatisierungsworkflow, um die HTML-Dokumentationsdateien mithilfe des ausgewählten Dokumentationsgenerators zu generieren und mit GitHub Pages bereitzustellen.