Die Integrität der Dokumentation einer API bestimmt, wie nützlich sie ist. Verwenden Sie beim Schreiben der Dokumentation von REST-APIs Standardverfahren, um ein Handbuch zu erstellen, das für alle Leser einfacher zu lesen und zu verstehen ist. Die Dokumentation von REST-APIs bietet eine Kurzanleitung, die alles enthält, was Sie über die API wissen müssen, einschließlich Informationen über Verfahren, Kategorien, Ergebnisarten, Parameter und mehr. In diesem Artikel finden Sie Informationen über REST-APIs, wie man REST-API-Dokumente schreibt und Tipps und Tools zum Schreiben von Dokumentation.
Über REST-APIs
REST-APIs erleichtern die Kommunikation zwischen verschiedenen Internetanwendungen. Sie können Daten von einem anderen Programm abrufen, wenn Sie ein solches verwenden. Sie können RESTful API anstelle der herkömmlichen Methoden verwenden, die länger dauern und weniger sicher sind. Mit einer API können Sie Daten von einem System abrufen, ohne mit der Benutzeroberfläche in Kontakt zu treten.
REST ist ein beliebter Architektur- und Programmieransatz für vernetzte Hypermedia-Plattformen und andere Webtechnologien. Die Instagram-API gibt beispielsweise den Status, die Identität, die Verbindungen und die freigegebenen Tweets des Nutzers zurück, wenn ein Programmierer das Objekt eines Kunden abrufen möchte. Dank der API-Integration ist dies machbar.
Wie schreibt man eine API-Dokumentation?
Eine bessere Dokumentation sollte sowohl als Leitfaden als auch als Lehrmittel dienen, so dass Entwickler die benötigten Details schnell auf einen Blick finden und anhand der Dokumentation lernen können, wie sie die von ihnen in Betracht gezogene Technik einbinden können. Folglich muss eine angemessene Dokumentation sowohl knapp als auch übersichtlich sein und Folgendes bieten:
- eine detaillierte Beschreibung der Funktion der Technik oder des Gegenstands
- Hinweise, die den Entwicklern wichtige Details vermitteln, z. B. Probleme und Warnungen
- Ein Beispielaufruf mit dem Inhalt des entsprechenden Medientyps
- Eine Checkliste der Variablen, die von dieser Technik verwendet werden, zusammen mit Informationen über ihre Art, besondere Strukturierungsanforderungen und ob sie notwendig sind.
- Ein Beispiel für eine Antwort mit Medientyp body
- Beispiele für Skripte in verschiedenen Sprachen, die den gesamten erforderlichen Code enthalten (z.B. Java, .Net, Ruby, etc.)
- SDK-Instanzen
- Sie demonstrieren, wie das SDK für ihren Dialekt verwendet werden kann, um den Dienst oder das Verfahren zu erreichen.
- Wertvolle Aktivitäten zum Testen und Ausprobieren von API-Anfragen (API Console, API Notebook)
- Abfragen und Situationen mit Codes werden häufig in Frage gestellt.
- Verweise auf verwandte Websites (andere Beispiele, Blogs, etc.)
Die besten Tipps für das Schreiben von RESTful API-Dokumentation
Planen Sie Ihre Strategie für die Erstellung der Dokumentation
Wenn Sie mit dem Dokumentationsprozess beginnen, müssen Sie eine gründliche Strategie entwickeln. Die Wahrscheinlichkeit, dass Sie erfolgreich sind, wird dadurch steigen. Verstehen Sie die Leser, für die Sie die Dokumentation erstellen, bevor Sie REST-APIs dokumentieren. Sie können die richtige Plattform, den richtigen Stil und das richtige Layout für Ihre Dokumentation wählen, wenn Sie sich über die Zielgruppe im Klaren sind.
Wenn Sie sich über die Ziele und den Umfang der Dokumentation von REST-APIs im Klaren sind, wird es Ihnen leichter fallen, relevantes Material zu erstellen, das die Nutzung Ihrer API verbessern wird. Sie können die Dokumentation so gestalten, dass sie die Anforderungen der Benutzer besser erfüllt, indem Sie REST-APIs unter Berücksichtigung dieser Anforderungen schreiben.
Denken Sie daran, dass die Benutzer eine mentale Vorstellung von Ihrem Betriebsszenario haben, wenn sie Ihre APIs verwenden. Zum Beispiel werden die Benutzer wahrscheinlich die API-Dokumente Kosten, Retouren, Kunden und Debitkarten in Betracht ziehen, wenn Sie eine Zahlungsmethode anbieten.
Daher ist es logisch, Ihre Dokumente auf diese Weise zu organisieren. Sehen Sie sich die Dokumentation für die Stripe-API an. Sie geben eine gute Einführung, bevor sie APIs logisch gruppieren. GitHub bietet ein solides Beispiel für RESTful-API-Dokumentation, die gut organisiert ist und Abschnitte für "GitHub-Informationen, Probleme und Mitglieder" enthält.
Mit GitHub können Sie Pull Requests, Zweige und mehr erstellen. Die API-Dokumente von GitHub sind Open Source. Das Beste an GitHub ist, dass das Unternehmen stets bestrebt ist, die Erfahrung von Entwicklern auf wichtige Weise zu verbessern.
Grundlegende Abschnitte einbeziehen
Eine exzellente RESTful-API-Dokumentation muss eine bestimmte Anzahl von Teilen enthalten. Diese Kernabschnitte tragen wesentlich zur Klarheit und Akzeptanz von REST-APIs bei, wenn sie dokumentiert werden. Sie sollten bei der Dokumentation von REST-APIs einige wesentliche Elemente berücksichtigen.
- Eine Einführung in die REST-API
- Wie man Benutzeranmeldeinformationen erhält
- Ressourcen, die für die Nutzung der API benötigt werden
- Fehlermeldungen bei der Kommunikation mit der API
- Bedingungen für die Nutzung
Bewahren Sie Integrität und vermeiden Sie Fachausdrücke
Eine weitere hilfreiche Methode für die RESTful-API-Dokumentation ist die konsistente Verwendung von Begriffen im gesamten Text. Verwenden Sie einen einheitlichen Schreibstil, der frei von sprachlichen und kodierungstechnischen Unstimmigkeiten ist. Entfernen Sie unklare oder schwer verständliche Abschnitte, nachdem Sie Ihren Inhalt gründlich Korrektur gelesen haben.
Verwenden Sie stets eine einheitliche Terminologie und ein einheitliches Vokabular. Lassen Sie Ihrer Fantasie freien Lauf, wenn Sie HTTP-Protokolle, Statuscodes und andere gebräuchliche Bezeichnungen verwenden, die zu Missverständnissen führen könnten. Bei der Beschreibung von REST-APIs sollte zum Beispiel das HTTP-Verb GET verwendet werden, um Daten von einer bestimmten Ressource abzufragen. Sie müssen nicht viele Begründungen schreiben, wenn Sie sich an bekannte Normen halten, und Ihr Dokument wird einfacher zu lesen sein. Es wäre auch hilfreich, wenn Sie in Ihrer API-Beschreibung nicht zu viel Fachsprache verwenden würden. Achten Sie darauf, eine einfache Sprache zu verwenden, die die Bedürfnisse Ihrer Zielgruppe anspricht.
Fügen Sie interaktive Illustrationen hinzu
Die meisten Entwickler testen gerne, ob das, was sie in der Dokumentation gelesen haben, effektiv ist. Fügen Sie in einer Programmiersprache, mit der die meisten Entwickler vertraut sind, dynamische Beispielprogramme ein. Dadurch wird die API-Entwicklung weniger kompliziert.
Die Einbeziehung dynamischer REST-API-Beispiele ist eine wirksame Methode, um die Lernkurve bei der Nutzung Ihrer API zu senken. Darüber hinaus können Sie Testinformationen einbeziehen, mit denen die Benutzer Vorschläge einreichen und die Art der erhaltenen Antworten prüfen können.
Wenn Sie REST-APIs dokumentieren, können Sie auch andere Materialien als Live-Beispiele einbeziehen. Dies hilft den Nutzern, die API über die in den Anleitungen enthaltenen Informationen hinaus optimal zu nutzen. Eine Anleitung zur Einrichtung eines Kontos, Frameworks, Entwicklungstools und Seminare sind einige Materialien, die zur Ergänzung der API-Beschreibung verwendet werden können.
Schreiben Sie für eine Einstiegsposition
Die Dokumentation wird oft von professionellen Autoren und nicht von Entwicklern erstellt. Das liegt daran, dass technische Redakteure darauf spezialisiert sind, technische Konzepte in verständliche Sprache zu übersetzen. Dennoch verwenden viele technische Redakteure in ihren Handbüchern technisches Vokabular. Jede API wird mit Blick auf eine bestimmte Zielgruppe entwickelt.
API-Dokumente werden von einem breiten Publikum betrachtet, darunter Entwickler, Beurteilungsteams und Beobachter. Die Entwickler beschäftigen sich mit der Dokumentation. Das Beurteilungsteam, z. B. Ingenieure und CTOs, erkennt schnell, ob die API geeignet ist, und die Beobachter, z. B. technische Redakteure, Reporter und Ihre Konkurrenten.
Diese Personen haben unterschiedliche Aufgaben und Talente und sollten beim Betrachten Ihrer REST-API-Dokumentation entspannt sein. Daher sollten Sie sich auf die unerfahrensten Verbraucher konzentrieren. Wenden Sie bei der Dokumentation von REST-APIs die oben genannten Techniken an, um zu gewährleisten, dass die REST-API-Dokumentation für Personen mit unterschiedlichem API-Wissen verständlich ist.
Das beste Werkzeug für die Erstellung von RESTful API-Dokumentation
Die Methode, mit der die technische Dokumentation mithilfe von Tools für Restful APIs rationalisiert wurde. Technische Redakteure können diese REST-API-Dokumentationstools verwenden, um technische Veröffentlichungen zu erstellen, wenn sie mit der Codierung vertraut sind. Da die Verwendung von API-Dokumentationserstellern weit verbreitet ist, sind die bekanntesten Hersteller, die kostenlos sind und OpenAPI v3 unterstützen, unten aufgeführt. Technische Redakteure nutzen diese Ressourcen, um REST-API-Dokumentation zu erstellen.
SwaggerHub
SwaggerHub ist eine digitale API-Dokumentationsplattform, die entwickelt wurde, um die Dokumentation von Rest-APIs zu rationalisieren und zu beschleunigen, was sie perfekt für Teams und Unternehmen macht. Mit dem API-Editor können Sie die OpenAPI-Spezifikationen (OAS), die früher als Swagger bezeichnet wurden, noch schneller einhalten.
Einige seiner Funktionen sind:
- Effektive Fehlerberichterstattung und automatische Vervollständigung der Sprache
- Integrierte API-Entwurfsrichtlinien, die kontinuierlich die Standards durchsetzen
- Websites zur Speicherung und Nutzung der OAS-Syntax, die für alle APIs gilt
- Problemverfolgung und Kommentare in Echtzeit
- Hervorragende Erfahrung für Entwickler
Redocly
Der Prozess der REST-API-Dokumentation wird durch die Workflows von Redocly automatisiert. Sie können Ihre Dokumentation wie Programmcode mit virtualisierten Dokumenten behandeln, indem Sie sie in einer speziellen Editionssoftware speichern, ein Prüfverfahren einrichten und sie an verschiedene Einstellungen übergeben. Redocly Mit den Benutzerrechten, der Versuchsprüfung und anderen Authentifizierungsmechanismen von können Sie zusätzlich gewährleisten, dass Ihr Team effektiv und sicher zusammenarbeitet. Die Anzeigefunktion von Redocly ist eine weitere einzigartige Funktion. Um sicherzustellen, dass Ihre Änderungen bewertet und diskutiert werden, bevor Sie sie an die Öffentlichkeit schicken, können Sie eine Vorschau für jedes Projekt und jede Patch-Anfrage anzeigen.
Stoplight
Mit dem REST-API-Schreibprogramm von Stoplight können Sie API-Dokumente digital erstellen und bereitstellen. Mit dieser Software können Sie dynamische REST-API-Dokumentation erstellen, die Sie intern und extern an die Allgemeinheit verteilen können. Sie können Anleitungen, Handbücher und Codebeispiele in verschiedenen Programmiersprachen wie JavaScript, Python und Java einbinden.
Sie können Ihre Dokumentation auf Stoplight veröffentlichen, eine der wichtigsten Funktionen unserer REST-API-Dokumentationslösung. Dadurch müssen Sie sich nicht mehr um den Betrieb von Servern kümmern und können ganz einfach Konnektoren zur Verwaltung von Berechtigungen und zur Verfolgung von Metriken verwenden.
ReadMe
Ihre API-Dokumente können mit ReadMe zu einem dynamischen Zentrum für Ihre Entwickler werden. Sie können in diesem Hub automatisch Code-Beispiele erstellen, das Material im ReadMe-Editor ändern, eine empfohlene Bearbeitung integrieren, auf Anfragen im Diskussionsforum antworten und vieles mehr.
Einer der wichtigsten Vorteile von ReadMe besteht darin, dass es Analysen wie Seitenbesuche, API-Anfragen, API-Fehlschläge und Abfragen auf verschiedenen Websites analysiert, so dass Sie sehen können, wie Ihre Anwendungsprogrammierschnittstelle und REST-API-Dokumentation im Laufe der Zeit genutzt wird. Anhand dieser Metriken kann Ihr Team feststellen, wo es seine Bemühungen zur Verbesserung konzentrieren muss.
apiDoc
Eine quelloffene REST-API-Dokumentationslösung namens apiDoc generiert Dokumentation aus einer Codebasis, die API-Details enthält. Sie ist mit praktisch jeder Programmiersprache kompatibel. Ingenieure können beobachten, was zwischen den Ausgaben einer API geändert wurde, da apiDoc dies ermöglicht. Dies erleichtert die saubere Handhabung von API-Aktualisierungen, oft auch als API-Versionierung bezeichnet.
DapperDox
DapperDox wurde von Verfassern von RESTful-API-Dokumentation für Verfasser von REST-API-Dokumentation entwickelt, um Verfassern die gewünschte Freiheit und Entwicklern die erforderliche Lesbarkeit zu bieten. Diese Lösung für Web-API-Dokumente ist ideal für die Erstellung einer kohärenten Dokumentation, die verständliche Anweisungen und Web-API-Standards enthält, da sie es den Autoren ermöglicht, einer erstellten Beschreibungsseite relevantes Material hinzuzufügen. Darüber hinaus können Sie bei Bedarf Querverweise einfügen, verschiedene API-Anforderungen als eine Gruppe von Waren beschreiben und Themen auswählen, um Ihre Dokumente unterschiedlich zu formatieren.
DocGen von LucyBot
Sie können dynamische API-Dokumentation mit LucyBot's DocGen erzeugen und verwalten. Dieses Programm erstellt die Dokumentation für jede API-Methode und jedes Argument und antwortet sofort. Sie können eine API-Konsole erstellen, die es Erstellern und Nutzern ermöglicht, API-Anfragen zu Testzwecken durchzuführen, um Ihre API zu untersuchen, Fehler zu beheben und sie möglicherweise besser zu verstehen. Sie können auch Prozesse erstellen, die den Benutzern genau zeigen, welchen Code sie erstellen müssen und welche Schritte sie befolgen müssen, um eine bestimmte Aufgabe in der von ihnen gewählten Software-Sprache zu erledigen.
AppMaster
Im Gegensatz zu anderen Plattformen, AppMaster muss ein Entwickler die REST-API-Dokumentation nicht mehr manuell erstellen und aktualisieren. Die Plattform generiert und aktualisiert automatisch die REST-API-Dokumentation im Format Swagger (OpenAPI) für jede Anwendung und enthält außerdem die Swagger-Benutzeroberfläche in jeder Serveranwendung, um Entwicklern von Drittanbietern die Integration in generierte Anwendungen zu erleichtern. Darüber hinaus fügt die Plattform AppMaster bei der Erstellung der REST-API-Dokumentation automatisch Beschreibungen der Endpunkte und der zugehörigen Geschäftsprozesse in die Beschreibung jedes Endpunkts ein, so dass der Entwickler keine Dokumentation mehr erstellen oder aktualisieren muss.
Abschließende Worte
Alle in diesem Artikel vorgestellten API-Dokumentationstools sind in der Lage, hochwertige API-Dokumentation zu erstellen. Es ist unmöglich, ein einziges Instrument als das beste zu bezeichnen. Die gesamte Erfahrung und die Kriterien einer API-Dokumentationssoftware werden durch die Standards, Konzepte, Ziele und Dokumentationsanforderungen des Kunden bestimmt.
