Wie dokumentieren Sie eine REST-API?

Question

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 nützlich genug zu wissen, dass etwas erwartet, dass XML gesendet wird und XML zurückgibt; 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 konnte ich bisher das Enunciate-Tool finden, 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?

Verbraucher meiner REST-API kann in jeder Sprache Python, Java, .NET sein, etc

Answer 1

Der Ansatz, den ich auf für mein Projekt entschieden haben, ist artikulieren. Scheint der De-facto-Standard für die REST-API-Dokumentation zu sein.

Answer 2

Ich bin mir nicht sicher, ob Sie nach einem Werkzeug fragen, das Sie dabei unterstützt, oder wenn Sie fragen, was die beste Praxis ist (oder beides).

Soweit es die Best Practices betrifft, gelten die gleichen Dinge für die REST-Dokumentation wie für andere Softwaredokumentationen - bieten Sie eine gute Landingpage mit Breite (dh eine Liste Ihrer Ressourcen mit einem Klappentext über ihre Aktivitäten und ihre URI) mit 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.

Twitter API main page

Sample drilldown of one resource

Ich liebe wirklich, dass die Drill-Down-Seite. 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 eine Antwort.

Answer 3

Ich kann falsch liegen, aber es scheint, als ob Sie etwas ähnlich wie ein WSDL und XML-Schema möchten, um Ihre API zu dokumentieren. Ich schlage vor, Joe Gregorios Beitrag auf Do we need WADL zu lesen? 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 Does REST need a description language? Es hat viele gute Links zu dieser Art von Diskussion.

Während sein Beitrag gibt Ihnen Ratschläge, was nicht zu tun ist, beantwortet es 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 zu beschreiben, Ihre Daten 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 umfangreiche, menschenlesbare Dokumentation mit Beispielen. Nur so kann ich Semantik richtig beschreiben. Ich mag die Verwendung von Sphinx, um diese Art von Dokumentation zu generieren.

Answer 4

Ich habe Erfahrung mit Enunciate, das ist toll, aber ich mag nicht wirklich die Clients, die Sie damit generieren können. Auf der anderen Seite habe ich swagger bei meinen letzten Projekten verwendet und es scheint meine Bedürfnisse zu erfüllen, es ist wirklich cool, Sie sollten es versuchen!

UPDATE 2016.03.08: Sieht aus wie Sie artikulieren können Prahlerei docs zu bauen.
Siehe this.