Fosrestbundle: Génération de la documentation de l'API REST à partir des routes

Consultez le http://getfrapi.com/ screencast pour vous inspirer.

Je l'ai déjà vu. Mais je n'aime pas beaucoup de choses dans leur réalisation. Tout d'abord, leur REST n'est pas RESTful :-D

"inspiration" et je ne parlais pas de leur repos mais de leur génération doc (et test) :)

Personnellement, je n'aime pas ça, mais pourrait-on discuter de la génération de la documentation au format WADL ?

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

Je me demande si une meilleure direction que la génération serait de fournir des assistants de vue permettant la construction rapide de contrôleurs/vues de documentation. Cela semble mieux que de simplement générer une structure et serait plus extensible/maintenable. En d'autres termes, je pense que la génération de documents API fonctionne très bien pour le cas d'utilisation de FRAPI (déposer dans une application), mais je me demande si nous avons besoin de cette fonctionnalité "telle quelle" ou si cela a même du sens.

Parlons-nous de la documentation pour les clients?

Gardez à l'esprit que c'est ce que REST essaie d'éviter :)

Odino : bien sûr. mais il y a des choses comme le fait que même si vous suivez HATEAOS, vous devez inspecter les en-têtes. même si vous devez savoir vous attendre à des codes d'état différents, il est toujours bon de savoir quels codes d'état sont "plus probables". c'est juste sympa pour un examen occasionnel de l'API.

aussi un autre sujet qui devrait être ignoré : certains clients aiment juste tuer des arbres et c'est bien de ne pas avoir à perdre beaucoup de temps à remplir ces pages de papier :)

d'accord, la seule chose que nous devrions éviter est de nous fier fortement à la documentation générée, sinon nous répliquerions WSDL

pouce vers le bas pour les tueurs d'arbres :)

Autant que je sache, les véritables documents de l'API REST concernent la définition des types de médias et de leurs relations, et non des URL. Par exemple http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

Mais pour de simples API HTTP, ce qui sera le cas pour 80% des projets web cette fonctionnalité serait tout de même utile.

Oui vladar, les modèles d'URI sont évidemment mauvais. Mais si nous devons développer un bundle REST, nous devons suivre ces principes.

Un modèle d'URI conviendrait bien à un ApiBundle

Pourrait être en mesure de prendre des concepts de http://swagger.wordnik.com/

:+1: à Swagger. Cela a l'air génial!

Pour créer une expérience similaire, nous pourrions être en mesure de :

• Méthodes d'analyse marquées comme @apidoc ou quelque chose
• Obtenir la description de la méthode et des paramètres de docblock sur les méthodes marquées @apidoc
• Autoriser le test en ligne des appels sur une base par action.

Dans l'ensemble, je pense que réaliser des écrans comme Swagger est assez faisable et a beaucoup de sens pour ce bundle.

Une autre option serait simplement de générer le JSON que Swagger consomme mais qui vient avec un certain poids (Java)... Je préférerais voir une implémentation "like".

Générer du JSON compatible a été ma première pensée. Je creuserai un peu plus le week-end, peut-être y a-t-il un prototypage rapide et sale possible.

@pminnieur semble que nous pourrions tout aussi bien fournir les mêmes fonctionnalités de base plutôt que de les intégrer.

Au moins, cela pourrait fonctionner comme https://github.com/FriendsOfSymfony/FOSJsRoutingBundle - en ajoutant simplement du HTML/CSS sophistiqué et en exposant vos itinéraires RESTful avec une sorte de documentation API. Peut-être que nous pourrions utiliser des annotations pour soutenir plus d'informations.

J'aimerais commencer par ça mais je pense qu'il serait préférable de mettre le code dans un bundle dédié (par exemple FOSRestAPIExplorerBundle). La question est de savoir si nous ne prendrons en charge que l'API Swagger (afin que Swagger soit utilisé pour visualiser les informations recueillies et exposées dans JSON) ou devons-nous également fournir notre propre interface Web ?

un bundle séparé semble être une bonne idée. si nous ne prenons en charge que swagger, nous voudrons peut-être le dire dans le nom du bundle. Je ne sais pas si nous voulons également soutenir autre chose. dépend de votre motivation et de la qualité de votre fanfaronnade. une question à propos de swagger : comment cela fonctionne-t-il avec des API internes que l'on ne veut pas exposer à un service externe ?

Je pense que vous devez simplement ne pas rendre publique l'URL renvoyant le Swagger JSON si vous ne voulez pas qu'elle soit publique ... :D Sérieusement, j'aimerais utiliser des annotations et si vous ne voulez pas qu'une route soit public, vous n'ajouterez pas l'annotation @Expose() ou ajouterez @Expose(false) -- quelque chose comme ça. Tout comme FOSJsRoutingBundle est configurable comment le gérer (exposer tout par défaut ou exposer la liste blanche). Si vous voulez dire "voici un lien pour notre API publique et ce lien est uniquement pour vous", nous pouvons ajouter une annotation comme @Api("public") et @Api("private") incluant le composant de sécurité afin que vous puissiez distribuer différentes API documentations à différentes personnes (et en contrôler l'accès).

Pour le nom : j'aimerais avoir un nom générique, Swagger serait le premier service de documentation de l'API à être supporté. Si les gens veulent ajouter un autre service, ils peuvent le faire (et ne doivent pas partir de zéro). @odino par exemple pourrait ajouter le support WADL. Au moins, j'aimerais également fournir une interface Web.

J'ai créé un référentiel GitHub jusqu'à présent pour collecter des idées et des problèmes avant de commencer. N'hésitez pas à ouvrir des problèmes pour toute question ou sujet à discuter (la dénomination pourrait également être discutée, bien sûr) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

OK bien. une fois que les choses ont pris forme .. nous pouvons le déplacer vers FOS

Envisagez-vous de profiter de https://github.com/wordnik/swagger-ui en tant que "displayer" ?

en premier lieu, oui. ne génère que du json conforme à la spécification swagger à utiliser par swagger-ui.

clôture en faveur de https://github.com/nelmio/NelmioApiDocBundle

Je sais que c'est très ancien, mais certaines choses ont changé depuis et j'ai trouvé cela assez rapidement en cherchant un package/bundle pour Swagger / Openapi.
Une chance de reconsidérer cela? Depuis le NelmioApiDocBundle est abandonné et je ne vois aucune véritable alternative qui s'intègre dans Symfony pour Swagger / OpenApi (ou tout autre vraiment, RAML, ...?).