Documentation automatique REST API in PHP
phpDocumentor semble être la norme pour documenter PHP, même si je dois me demander pourquoi il n'a pas été mis à jour depuis des années ..?
Cependant, il ne semble pas approprié de documenter les points d'entrée pour une REST; IE, points d'entrée accessibles en externe qu'un utilisateur final de votre système serait intéressé, par opposition à documenter tous les classes internes et autres - quelque chose qui n'intéresse que les développeurs de l'api.
Je cherche quelque chose où je pourrais dire, hé cette méthode ici est accessible de l'extérieur via REST à cette URL, voici le GET ou POST qu'il prend, il prend en charge les méthodes HTTP GET/POST/etc, il renvoie JSON ou XML ou autre.
Ces informations pourraient produire un document API. Il pourrait également être utilisé par le code en interne pour filtrer automatiquement les entrées, valider les sorties, créer des tests unitaires de base, etc.
Je connais 3 PHP intégrations avec swagger:
Tout devrait aider à créer automatiquement une spécification swagger, qui vous donne accès à partir de swagger-ui. Ensuite, vous pouvez générer des clients api, etc.
J'ai trouvé un excellent paquet de nœuds nommé apidoc qui fait un travail formidable pour documenter RESTfuls. Il permet à des tonnes de balises spécifiques à l'API de faire avec des paramètres et des choses comme ça, mais ce qui m'a vraiment vendu, ce sont ses formulaires de test in-doc générés pour chaque méthode.
Je l'utilise dans mon projet de squelette devops sur https://github.com/ardkevin84/devops.skel.php-with-docs-metrics , mais vous pouvez voir sortie réelle dans mon projet api callloop à https://github.com/ardkevin84/api.callloop . L'index apidoc est build/api-docs/apidoc/index.html
Le seul inconvénient, s'il en est un, est qu'il prend - naturellement - ses propres docblocks. Cependant, il ne se heurte pas aux Docblocks "natifs". Les blocs apidoc n'ont pas besoin de précéder une méthode, donc je les regroupe généralement en haut de mon fichier de noeud final où les autres moteurs de doc ne les associeront pas à un doc de classe.
Un sous-produit: cela fonctionne grand avec des façades; J'utilise beaucoup la façade et l'usine dans mes points d'extrémité, et l'analyseur apidoc me permet de gérer les conditions de la façade séparément. Dans l'exemple ci-dessous, "s'abonner", "se désabonner" et "déclencheur" sont gérés par un seul point d'entrée, mais ils sont documentés séparément.
Exemple: ce Docblocks
/**
* @api {get} ?action=:action&first=:firstname&last=:lastname&email=:useremail&phone=:phone&gid=:groupid Subscribe
* @apiSampleRequest http://www.example.com/rest/callloop.php
* @apiName Subscribe
* @apiGroup Subscription
* @apiDescription subscribes a user to the provided group
* @apiParam {string="subscribe","unsubscribe","trigger"} action=subscribe API Action to call. For subscriptions, use "subscribe"
* @apiParam {String} [first] Optional first name
* @apiParam {String} [last] Optional last name
* @apiParam {String} [email] Optional user email
* @apiParam {String} phone User's mobile phone number
*/
est requis pour générer cette sortie, avec le formulaire de test 
important, si vous utilisez $ _GET standard avec des paramètres de requête: Le package installé à partir du nœud ne prend pas en charge les points d'accès comme service.php?param=value, mais il y a une pull request dans le dépôt git à https://github.com/apidoc/apidoc/pull/189 qui résout ce problème. Il s'agit d'une correction de base du modèle par défaut. J'ai patché les quelques lignes dans mon package de nœuds et cela fonctionne comme un charme.
Auto-promotion sans vergogne: Ceci est probablement beaucoup plus facile à utiliser sous une construction automatisée. Consultez mon projet devops ci-dessus pour un kickstart;) Il est dérivé de jenkins-php, mais ajoute plusieurs moteurs de documentation et des cibles de stub pour des choses comme pousser les docs\metrics générés vers un chemin localhost et empaqueter la sortie pour publication (Zip, tar, etc. )
Une API RESTful doit être entièrement détectable et auto-documentée. Vous n'avez besoin que d'une URL et tout ce qui y est lié doit se décrire. Cela ressemble à une utopie, mais c'est faisable.
Par exemple, commençons par un exemple d'URL de type stackoverflow: http://restfuloverflow.com (illustratif)
La première chose que vous faites sur une ressource RESTful est une requête OPTIONS. Vous devez toujours inclure un en-tête Accept pour demander au serveur de répondre au type MIME le plus approprié:
OPTIONS * HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com
Le serveur doit indiquer au client ce qu'il est possible de faire sur cette URL:
HTTP/1.1 200 Ok
Allow: GET, POST, PUT, DELETE, OPTIONS, TRACE, PATCH
Il s'agit de l'API RESTful vous indiquant que ce service prend en charge ces méthodes. Le premier que vous allez essayer est quelque chose comme la demande ci-dessous. Un utilisateur frappant l'API avec un navigateur devrait fonctionner de la même manière.
GET / HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com
Le serveur doit alors renvoyer certains liens pointant vers des ressources connexes, si disponibles:
HTTP/1.1 200 Ok
Content-Type: text/xml
<?xml version="1.0">
<qa>
<link href="/questions" title="Questions"/>
<link href="/tags" title="Tags"/>
<link href="/users" title="Users"/>
</qa>
Une version HTML doit utiliser <a> les liens et les réponses JSON doivent utiliser l'attribut JSON-Schema links.
Disons que le client décide maintenant qu'il veut savoir quoi faire des questions:
OPTIONS /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json
Une réponse possible pourrait être:
HTTP/1.1 200 Ok
Allow: GET, POST
Content-Type: text/xml
<?xml version="1.0">
<xsd:element name="question">
<!-- XML Schema describing a question -->
</xsd:element>
Eh bien, le serveur nous a dit qu'il était possible de GET et POST une nouvelle question. Il nous a également dit à quoi ressemble une question en XML en fournissant un schéma XML. Un JSON-SCHEMA pourrait être fourni pour JSON, et en HTML, un formulaire pour les nouvelles questions pourrait être fourni.
Supposons que l'utilisateur souhaite obtenir des questions:
GET /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json
Ensuite, le serveur répond:
HTTP/1.1 200 Ok
Content-Type: text/xml
<?xml version="1.0">
<questions>
<link href="/questions/intersting" title="Intersting Questions"/>
<link href="/questions/hot" title="Hot Questions"/>
</questions>
Maintenant, tout est à nouveau lié. La chose continue d'une manière que le service se décrit. Netflix API suit des principes similaires, mais manque de fonctionnalités de découverte automatique.
Cette API du gouvernement brésilien se décrit en utilisant RDF. C'est l'un des meilleurs échantillons RESTful que j'ai jamais vus. Essayez de remplacer .rdf par .xml, .json ou .html. (Tout est en portugais, désolé pour ça).
Le meilleur outil pour les API RESTful dans PHP est Respect\Rest . Il a la plupart du flux de travail que j'ai décrit ici déjà démarré, et de nouvelles fonctionnalités arrivent (c'est toujours en version 0.4x).
Le coût de construction d'un système de documentation pour les applications RESTful est le même que pour la construction d'une application RESTful. C'est pourquoi il y a si peu d'outils comme ça, et généralement ils ne sont pas si bons.
Swagger semble prometteur, mais il faudra que votre API s'expose de manière compatible ... c'est plutôt sympa, cependant, avec une console de test, etc. entièrement intégrée ... vous pouvez télécharger une version javascript et l'exécuter sur votre serveur à côté de l'api php.
EDIT: voici le lien, ce n'est pas si facile à trouver sur google si vous n'avez pas le nom complet ... lol ... Swagger-UI: https://github.com/wordnik/swagger-ui
La chose la plus simple à faire est d'utiliser un tokenizer/parser docblock. Il y en a quelques-uns (je vais brancher le mien sous peu), mais fondamentalement, ils peuvent examiner le docblock et tokenize toutes les balises de docblock personnalisées (ou non personnalisées). Je l'ai utilisé dans un de mes cadres pour définir les types d'aides d'affichage via une balise appelée "@helperType".
Comme je l'ai dit, il y en a beaucoup, mais voici le mien pour vous aider à démarrer: https://github.com/masterexploder/DocumentingReflectionMethod
Fondamentalement, utilisez quelque chose comme ça et vous pouvez l'utiliser à la fois pour générer vos documents et pour faire des choses comme le filtrage automatique, la validation, etc.
En ce qui concerne la création de tests unitaires, PHPUnit peut les générer automatiquement à partir de vos classes (consultez leurs documents pour plus d'informations: http://www.phpunit.de/manual/3.5/en/skeleton-generator.html#skeleton -generator.test
Vous pouvez également demander à phpdocumenter d'analyser vos balises personnalisées: http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.customtags
Enfin, il existe un framework (à ma connaissance, je suis sûr qu'il y en a des tonnes) qui utilise des annotations pour faire toutes sortes de bonté reposante (peut-être pour vous épargner du travail): https: // github. com/évidement/évidement
J'espère que cela pourra aider!