Wie dokumentieren Sie eine REST-API? Nicht nur die Dokumentation dessen, was die Ressourcen sind, sondern in Wirklichkeit werden die Daten, die in der Anfrage gesendet werden und welche Daten in der Antwort zurückgesendet werden. Es ist nicht sinnvoll genug zu wissen, dass etwas erwartet, dass XML gesendet wird und gibt XML zurück; oder JASN; oder Wasauchimmer. Wie dokumentieren Sie die Daten, die in der Anfrage gesendet werden, und die Daten, die in der Antwort gesendet werden?
Am besten finde ich bisher das Tool "Enunciate", mit dem Sie Ihre REST-API und die Datenelemente dokumentieren können. Gibt es die richtige Art von Tool für diese und verpasse ich irgendwelche anderen Tools, die dies bieten, die ich mir anschauen sollte?
Die Nutzer meiner REST-API können in einer beliebigen Sprache Python, Java, .NET usw. sein.
Der Ansatz, den ich für mein Projekt gewählt habe, lautet Enunciate. Scheint der De-facto-Standard für die REST-API-Dokumentation zu sein.
Ich habe Erfahrung mit Enunciate, was großartig ist, aber ich mag die Clients, die Sie damit erzeugen können, nicht wirklich. Andererseits habe ich swagger bei meinen letzten Projekten verwendet und es scheint meinen Bedürfnissen zu entsprechen, es ist wirklich cool, dass du es geben solltest ein Versuch!
UPDATE 03/08/2016: Sieht so aus, als könnten Sie Enunciate verwenden, um swagger -Dokumente zu erstellen.
Siehe dies .
Ich könnte mich irren, aber es scheint so, als ob Sie etwas Ähnliches wie ein WSDL- und XML-Schema möchten, um Ihre API zu dokumentieren. Ich schlage vor, Joe Gregorios Beitrag auf Brauchen wir WADL ? Es gibt eine gute Diskussion darüber, warum dieser Ansatz nicht für eine REST-API verwendet werden sollte. Wenn Sie nicht den gesamten Artikel lesen möchten, ist die Grundidee, dass API-ähnliche Dokumentation (d. H. WADL) niemals ausreichend sein wird und zu spröden Schnittstellen führen wird. Ein weiterer guter Artikel ist Benötigt REST eine Beschreibungssprache ? Es hat viele gute Links zu dieser Art von Diskussion.
Während sein Beitrag Ihnen Ratschläge gibt, was nicht zu tun ist, beantwortet er nicht wirklich die Frage, was Sie tun sollten. Das große an REST ist die Idee einer einheitlichen Schnittstelle. Mit anderen Worten, GET, PUT, POST und DELETE sollten genau das tun, was Sie Ihrer Meinung nach tun sollten. GET ruft eine Repräsentation der Ressource, PUT-Updates, POST-Creatives und DELETE-Delete ab.
Die große Frage ist dann, Ihre Daten zu beschreiben und was es bedeutet. Sie können immer den Weg der Definition eines XML-Schemas oder etwas Ähnlichem gehen und Dokumentation aus dem Schema generieren. Persönlich finde ich keine maschinengenerierte Dokumentation, die nützlich ist.
Meiner Meinung nach haben die besten Datenformate eine umfangreiche, menschenlesbare Dokumentation mit Beispielen. Nur so kann ich Semantik richtig beschreiben. Ich mag die Verwendung von Sphinx , um diese Art von Dokumentation zu erstellen.
Ich bin mir nicht sicher, ob Sie nach einem Werkzeug fragen, das Sie dabei unterstützt, oder wenn Sie fragen, was die beste Vorgehensweise ist (oder beides).
Was Best Practices betrifft, gelten die gleichen Dinge für die REST-Dokumentation wie für andere Softwaredokumentationen - bieten Sie eine gute Zielseite mit einer Breite (dh eine Liste Ihrer Ressourcen, die logisch mit einem Klappentext über ihre Aufgaben und deren URI organisiert sind) an Drill-Down-Seiten, die ausführlich erklären, was jeder tut, mit Beispielen. Die REST-API von Twitter ist sehr gut dokumentiert und sollte ein gutes Modell sein.
Beispielaufriss einer Ressource
Ich liebe diese Drilldown-Seite wirklich. Es listet alle benötigten Parameter mit einer Beschreibung auf. Es hat eine Sidebar, die die unterstützten Typen auflistet. Es enthält Links zu verwandten Seiten und anderen Seiten mit demselben Tag. Es hat eine Beispielanforderung und Antwort.