Fosrestbundle: Generierung der REST-API-Dokumentation aus Routen

Sehen Sie sich den http://getfrapi.com/ Screencast an, um sich inspirieren zu lassen.

Ich habe es schon gesehen. Aber viele Dinge gefallen mir in ihrer Umsetzung nicht. Zunächst einmal ist ihr REST nicht RESTful :-D

"Inspiration" und ich habe nicht über ihren Rest gesprochen, sondern über ihre Dokument- (und Test-) Generation :)

Mir persönlich gefällt es nicht, aber könnten wir über die Generierung der Dokumentation im WADL-Format diskutieren?

http://www.w3.org/Submission/wadl/

Ich frage mich, ob eine bessere Richtung als die Generierung darin bestehen würde, einige Ansichtshelfer bereitzustellen, die eine schnelle Erstellung von Dokumentations-Controllern/Ansichten ermöglichen. Dies scheint besser zu sein, als einfach eine Struktur zu generieren, und wäre erweiterbarer/wartbarer. Mit anderen Worten, ich denke, das Generieren von API-Dokumenten funktioniert hervorragend für den Anwendungsfall von FRAPI (Drop in eine App), aber ich frage mich, ob wir diese Funktion "so wie sie ist" benötigen oder ob sie überhaupt Sinn macht.

Reden wir über Dokumentation für die Kunden?

Denken Sie daran, das ist es, was REST zu vermeiden versucht :)

odino: sicher. aber es gibt Dinge wie die Tatsache, dass Sie Header überprüfen müssen, selbst wenn Sie HATEAOS folgen. Auch wenn Sie wissen sollten, dass Sie mit unterschiedlichen Statuscodes rechnen müssen, ist es immer noch gut zu wissen, welche Statuscodes "wahrscheinlicher" sind. Es ist einfach schön, um die API beiläufig zu überprüfen.

Auch ein anderes Thema, das ignoriert werden sollte: Einige Kunden mögen es einfach, Bäume zu töten, und es ist schön, nicht viel Zeit damit verschwenden zu müssen, diese Seiten Papier zu füllen :)

Zustimmen, das einzige, was wir vermeiden sollten, ist, sich stark auf die generierte Dokumentation zu verlassen, da wir sonst WSDL replizieren würden

Daumen runter für Baumkiller :)

Soweit ich weiß, geht es in echten REST-API-Dokumenten um die Definition von Medientypen und ihren Beziehungen, nicht um URLs. ZB http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

Aber für einfache HTTP-APIs, was bei 80% der Webprojekte der Fall sein wird, wäre diese Funktion immer noch nützlich.

Ja, vladar, URI-Vorlagen sind offensichtlich böse. Aber wenn wir ein REST-Bundle entwickeln müssen, sollten wir diesen Prinzipien folgen.

Eine URI-Vorlage würde gut zu einem ApiBundle passen

Könnte Konzepte von http://swagger.wordnik.com/ übernehmen

:+1: zu Swagger. Das sieht toll aus!

Um ein ähnliches Erlebnis zu schaffen, können wir möglicherweise:

• Analysieren Sie Methoden, die als @apidoc oder so gekennzeichnet sind
• Holen Sie sich eine Beschreibung der Methode und der Parameter von docblock auf @apidoc markierten Methoden
• Ermöglichen Sie das Inline-Testen von Anrufen pro Aktion.

Alles in allem denke ich, dass das Erreichen von Bildschirmen wie Swagger ziemlich machbar ist und für dieses Bundle sehr sinnvoll ist.

Eine andere Option wäre einfach das Generieren des JSON, das Swagger verbraucht, aber das hat etwas Gewicht (Java) ... Ich würde lieber eine "like" -Implementierung sehen.

Kompatibles JSON zu generieren war mein erster Gedanke. Ich werde am Wochenende ein bisschen tiefer graben, vielleicht gibt es ein schnelles und schmutziges Prototyping.

@pminnieur scheint, als könnten wir genauso einfach die gleiche grundlegende Funktionalität bereitstellen, anstatt sie zu integrieren.

Zumindest könnte es wie https://github.com/FriendsOfSymfony/FOSJsRoutingBundle funktionieren – fügen Sie einfach etwas ausgefallenes HTML/CSS hinzu und stellen Sie Ihre RESTful-Routen mit einer Art API-Dokumentation bereit. Vielleicht könnten wir einige Anmerkungen verwenden, um weitere Informationen zu unterstützen.

Ich würde gerne damit beginnen, aber ich denke, es wäre besser, den Code in ein dediziertes Bundle (z. B. FOSRestAPIExplorerBundle) zu packen. Die Frage ist, sollen wir nur die Swagger-API unterstützen (damit Swagger verwendet wird, um die gesammelten und in JSON bereitgestellten Informationen zu visualisieren) oder sollen wir auch unsere eigene Webschnittstelle bereitstellen?

ein separates Bundle klingt nach einer guten Idee. Wenn wir nur Swagger unterstützen, möchten wir dies vielleicht im Bundle-Namen erwähnen. Ich weiß nicht, ob wir auch etwas anderes unterstützen wollen. hängt von Ihrer Motivation und der Qualität des Prahlens ab. Eine Frage zum Prahlen: Wie funktioniert das mit internen APIs, die man keinem externen Dienst aussetzen möchte?

Ich denke, Sie müssen die URL, die den Swagger-JSON zurückgibt, einfach nicht öffentlich machen, wenn Sie nicht möchten, dass sie öffentlich ist ... :D Im Ernst, ich möchte Anmerkungen verwenden und wenn Sie keine Route haben möchten public, fügen Sie nicht die Anmerkung @Expose() oder @Expose(false) hinzu – etwas in der Art. Genau wie FOSJsRoutingBundle ist konfigurierbar, wie damit umgegangen werden soll (standardmäßig alles anzeigen oder Whitelisting anzeigen). Wenn Sie meinen „hier ist ein Link für unsere öffentliche API und dieser Link ist nur für Sie“, können wir eine Anmerkung wie @Api("public") und @Api("private") einschließlich der Sicherheitskomponente hinzufügen, damit Sie eine andere API verteilen können Dokumentationen an verschiedene Personen weitergeben (und den Zugriff darauf kontrollieren).

Zum Namen: Ich hätte gerne einen generischen Namen, Swagger wäre der erste unterstützte API-Dokumentationsdienst. Wenn die Leute einen anderen Dienst hinzufügen möchten, können sie es einfach tun (und müssen nicht bei Null anfangen). @odino könnte zum Beispiel die WADL-Unterstützung hinzufügen. Zumindest möchte ich auch ein Webinterface bereitstellen.

Ich habe bisher ein GitHub-Repository erstellt, um Ideen und Probleme zu sammeln, bevor wir loslegen. Fühlen Sie sich frei, Themen für Fragen oder Diskussionsthemen zu eröffnen (Namen könnten natürlich auch diskutiert werden) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

OK gut. Sobald sich die Dinge entwickelt haben, können wir es zu FOS verschieben

Planen Sie, https://github.com/wordnik/swagger-ui als „Displayer“ zu nutzen?

in erster linie, ja. Generieren Sie nur Swagger-Spec-konformen JSON, der von der Swagger-UI verwendet werden soll.

schließen zugunsten von https://github.com/nelmio/NelmioApiDocBundle

Ich weiß, dass dies sehr alt ist, aber einige Dinge haben sich seitdem geändert und ich habe dies relativ schnell gefunden, als ich nach einem Paket/Bundle für Swagger / Openapi gesucht habe.
Gibt es eine Möglichkeit, dies zu überdenken? Da das NelmioApiDocBundle aufgegeben wird und ich keine wirkliche Alternative sehe, die sich in Symfony für Swagger / OpenApi (oder wirklich irgendein anderes RAML, ...?) integriert.