Ich schreibe eine Spezifikation für eine RESTful-API für einen neuen internen Webdienst. Es ist nicht sehr lang und ziemlich einfach, aber trotzdem verwende ich zum ersten Mal striktes REST (im Gegensatz zu Betrug aus praktischen Gründen - Vermeiden PUTund DELETEweil sie in PHP schmerzhaft sind und so weiter). Ich habe mich gefragt, ob es Standardmethoden oder Best Practices für die Dokumentation einer REST-Schnittstelle gibt. Ich möchte, dass der Rest des Teams es auf einen Blick versteht und dass jeder, der einen Client schreiben möchte, dies tun kann, ohne den zugrunde liegenden Code zu verstehen.
rest
documentation
Samir Talwar
quelle
quelle
Antworten:
Sicher, REST-APIs sollten idealerweise HATEOAS verwenden und hypertextgesteuert sein (bei starker Verwendung von Medientypen), aber es ist auch hilfreich, eine einfache, benutzerfreundliche Dokumentation zu haben, an der Entwickler arbeiten können.
Einige spezielle Tools, die zum Generieren der folgenden Dokumentation hilfreich sind:
quelle
Ich habe http://apiary.io verwendet , was ziemlich nett ist. Sie können die API-Dokumentation auch nach github exportieren.
quelle
In Roys Post hier sagt er
quelle
Eine gute ReST-Dokumentation würde bedeuten, dass Sie Ihren Medientyp und nur Ihren Medientyp dokumentieren.
In einem typischen Szenario würden Sie ein Dokument wie folgt erstellen:
Die Acme Corp XML-Formate
Linkerkennung
Links zu verschiedenen Ressourcen werden in einem Dokument beschrieben, das gefunden werden kann, indem eine GET- oder HEAD-Anforderung an den Server über einen Lesezeichen-URI (normalerweise das Stammverzeichnis des Servers, http://www.acme.org ) gesendet und nach einem gesucht wird HTTP Link Header:
Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xmlDabei ist der
relTeil die Verknüpfungsbeziehung undxxxder URI, für den die Beziehung hergestellt wurde.Beziehungen verknüpfen
Dieses Dokument definiert die folgenden Beziehungsnamen:
Medientypen
Dies
application/vnd.acme.services+xmlist ein Dokument mit einerxmlSerialisierung, das eine Liste von Links beschreibt, die eine Anwendung möglicherweise verarbeiten möchte.<links> <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" /> </link>Das
applcation/vnd.acme.customers+xmlist ein Dokument mit einerxmlSerialisierung, die Kunden beschreibt.Beispieldokumente:
<customers> <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" /> </customer>usw...
Der Punkt ist, dem Entwickler eine Möglichkeit zu geben, den von Ihnen definierten Links zu folgen. Suchen Sie zuerst den Link zum Index damit sie die Liste der Dinge erhalten, zu denen sie navigieren können.
Sobald sie dieses Dokument entdeckt haben, stellen sie fest, dass sie eine Liste von Kunden bei einem bestimmten Uri sehen und eine ausführen können
GETkönnen.Wenn sie einen Kunden von Interesse finden, können sie dem in definierten Link folgen
/customers/customer/@hrefund a ausgebenGET, um eine Darstellung dieses Kunden abzurufen.Von dort aus kann Ihr Medientyp Aktionen einbetten, die dem Benutzer mithilfe weiterer Links zur Verfügung stehen. Sie haben auch die zusätzliche Möglichkeit, eine OPTIONS-Anforderung für die Ressource auszugeben, um festzustellen, ob Sie das Löschen der Ressource zulassen können, oder einen PUT, wenn Sie das Dokument nach der Änderung wieder speichern können.
Eine gute Dokumentation gibt es also nie:
Bei alledem geht es darum, eine minimale Kopplung zwischen Clients und Servern zu erreichen. Der Client kann sehr intelligent Ressourcen anzeigen und entdecken (Formulare anzeigen und Gott weiß was noch), ist aber völlig dumm, was der eigentliche Workflow ist: Der Server entscheidet.
quelle
In meinem Unternehmen haben wir WADL , Web Application Description Language, sehr gerne verwendet . Wikipedia beschreibt es als: "ein XML-basiertes Dateiformat, das eine maschinenlesbare Beschreibung von HTTP-basierten Webanwendungen bietet". Ich finde es einfach, rohe WADL zu schreiben, zu lesen und zu verstehen, und sie ist direkt RESTful-Konzepten zugeordnet. Das offizielle Projekt bietet eine einfache Spezifikation, XSD- und RELAX NG-Schemata sowie Java-Tools.
Für die Arbeit mit WADL stehen eine Reihe von Tools und Ressourcen zur Verfügung, darunter:
Ein Tipp: Versuchen Sie, lesbare Dokumentationen wie Beschreibungen, Konzepte, Erste Schritte, Verwendungstipps usw. in das
docElement des WADL-Dokuments aufzunehmen, indem Sie HTML-Elemente mithilfe des XHTML-Namespace einfügen. Es kann einen großen Unterschied machen!quelle
Anfangs haben wir uns für die statische Dokumentation von Ressourcen entschieden, mussten aber einfach zu viele Fragen stellen. Schließlich haben wir Live-Dokumentationsseiten mit IO / Docs (eigentlich eine Abzweigung ) verwendet. Ich habe großartig gearbeitet.
quelle
Möglicherweise finden Sie Rest-Tool hilfreich.
Es folgt einem sprachunabhängigen Ansatz zum Schreiben von Spezifikationen, zur Scheinimplementierung und zum automatisierten Testen von Einheiten für RESTful-APIs. Es bietet auch ein Kochbuch, obwohl es sich in einem sehr frühen Stadium befindet, aber sein Inhalt wächst kontinuierlich.
Die Dienste, die Sie gerade beschrieben haben, können sofort verwendet werden, sodass Sie auch gut experimentieren können.
quelle
Um Verständnis / Dokumentation zu schaffen, werden nicht immer schwergewichtige Lösungen benötigt. Beispiele für (großartige) Schwergewichtswerkzeuge sind: IO / Docs / Apigee (obwohl großartige Werkzeuge).
Für kleine Projekte, die bereits ein Docchain-Setup haben (doxygen / phpdoc / phpdoctor / custom / etc), verwende ich das folgende Shellscript, um nur die Seite in die vollständig generierte Dokumentation aufzunehmen:
https://gist.github.com/4496972
Eine Demo: http://pastie.org/5657190
Es werden nur benutzerdefinierte Kommentar-Tags in Ihrem Quellcode verwendet. Es kann auch ein guter Ausgangspunkt für die Dokumentation eines beliebigen Quellcodes (einer beliebigen Sprache) sein.
quelle