Erstellen der API-Dokumentation

Das Erstellen der API-Dokumentation für Ihr Quellcode-Repository ist sehr wichtig. Eine gute Dokumentation hilft Entwicklern, Ihre API einfach zu verstehen, zu verwalten und zu verwenden. In der vollständigen Dokumentation wird erläutert, wie die API funktioniert, welche Eingaben erforderlich sind, welche Ausgabe sie liefert, und wie die API-Endpunkte verwendet werden. Beim Erstellen der API-Dokumentation sollten Sie das beste Format (z. B. OpenAPI-Spezifikation oder Markdown) auswählen, Beispiele und Verwendungsszenarien einschließen, sie bei Codeänderungen aktualisieren und API-Benutzer um Feedback bitten, es besser zu machen. Obwohl der allgemeine Ansatz für die API-Dokumentation überall funktioniert, gibt es einige Unterschiede zwischen Azure DevOps und GitHub.

Erstellen der API-Dokumentation in Azure DevOps

Um einem Azure DevOps-Projekt eine API-Dokumentation effizient hinzuzufügen, sollten Sie ein dediziertes Dokumentationstool verwenden, das mit Ihrem Entwicklungsworkflow funktioniert. Beliebte Auswahlmöglichkeiten sind Swagger (OpenAPI), API Blueprint und Markdown-basierte Dokumentationssysteme wie MkDocs oder Docusaurus. Die Azure DevOps-Integration hilft bei der Automatisierung der Dokumentationserstellung und hält sie mit Ihrem Code synchronisiert. Die meisten Dokumentationstools können auch Inlinekommentare lesen und in automatisch generierte Dokumentation einschließen.

Sie sollten die API-Dokumentation an einem zentralen Ort veröffentlichen, auf den Ihre Teammitglieder und Projektbeteiligte zugreifen können. Dies kann eine dedizierte Dokumentationswebsite, ein Wiki in Azure DevOps oder ein externes Dokumentationsportal sein.

Sie können auch direkt in Ihrem Code Code-Anmerkungen oder Dekoratoren verwenden, um Metadaten hinzuzufügen, die Ihre API-Endpunkte beschreiben. Tools wie Swagger Codegen oder Springfox können diese Anmerkungen verarbeiten und OpenAPI-Spezifikationsdateien erstellen.

Richten Sie automatisierte Prozesse in Ihren Azure-Pipelines ein, um die API-Dokumentation automatisch zu erstellen, wenn eine Änderung am Code vorhanden ist. Dadurch wird sichergestellt, dass Ihre Dokumentation aktuell bleibt und die neuesten Änderungen in Ihren APIs widerspiegelt.

Erstellen der API-Dokumentation in GitHub

Wenn Sie GitHub verwenden, sollten Sie die API-Dokumentation mithilfe von Tools erstellen, die Teil des GitHub-Ökosystems sind.

Dokumentieren Sie zunächst Ihre API-Endpunkte, Vorgänge, Parameter, Antworten und andere relevante Informationen. Erwägen Sie die Erstellung dieser Dokumentation im Markdown-Format, da sie häufig unterstützt und einfach zu verwenden ist. Definieren Sie eine konsistente Struktur für einzelne Dokumente, wobei sie in Abschnitte unterteilt werden, die Authentifizierung, Endpunkte, Anforderungsparameter, Antwortbeispiele usw. beschreiben.

Wie bei Azure DevOps können Sie Dokumentationsgeneratoren oder statische Websitegeneratoren verwenden, um das Erstellen der API-Dokumentation aus Markdown-Dateien zu vereinfachen. Beliebte Wahlmöglichkeiten sind Jekyll, MkDocs, Docusaurus und Hugo. Richten Sie den Generator ein, um Markdown-Dateien zu lesen und statische HTML-Seiten zu erstellen. Sie können das Layout, das Design und die Formatierung an das Branding und die Einstellungen Ihres Projekts anpassen.

Um den HTML-Inhalt zu veröffentlichen, verwenden Sie GitHub-Seiten, mit denen Sie statische Websites direkt aus Ihrem GitHub-Repository hosten können. Sie können zu diesem Zweck eine dedizierte Verzweigung erstellen und die HTML-Dateien in diese Verzweigung übertragen. Sie können Auch GitHub-Aktionen verwenden, um Ihre API-Dokumentation automatisch zu erstellen und bereitzustellen, wenn eine Änderung an den Dokumentationsdateien oder dem Code vorhanden ist.

Richten Sie GitHub-Aktionen ein, um Ihre API-Dokumentation automatisch zu erstellen und bereitzustellen, wenn eine Änderung an den Dokumentationsdateien oder dem Code vorhanden ist. Konfigurieren Sie den Automatisierungsworkflow, um die HTML-Dokumentationsdateien mithilfe Ihres ausgewählten Dokumentationsgenerators zu erstellen und auf GitHub-Seiten bereitzustellen.