Documentación automática API REST en PHP

Question

phpDocumentor parece ser el estándar para la documentación de código PHP, aunque tengo que preguntarme por qué no se ha actualizado en años ...?

Sin embargo, no parece adecuado para documentar los puntos de entrada para una API REST; IE, puntos de entrada accesibles desde el exterior en los que un usuario final de su sistema estaría interesado, en lugar de documentar todas las clases internas y tal, algo que solo interesa a los desarrolladores de la API.

Estoy buscando algo donde pueda decir, hey, este método aquí es accesible desde el REST en esta URL, aquí están los argumentos GET o POST, soporta métodos HTTP GET/POST/etc, devuelve JSON o XML o lo que sea.

Esta información podría producir un documento API. También podría ser utilizado por el código internamente para filtrar automáticamente las entradas, validar la salida, crear pruebas básicas de unidades, etc.

Answer 1

Lo más fácil es usar un tokenizer/parser de docblock. Hay un par de ellos (voy a conectar el mío en breve), pero básicamente pueden examinar el docblock y tokenizar cualquier etiqueta docblock personalizada (o no personalizada). Lo utilicé dentro de un marco mío para definir ver tipos de ayudantes a través de una etiqueta llamada "@helperType".

Como dije, hay un montón por ahí, pero aquí está la mía para que pueda empezar: https://github.com/masterexploder/DocumentingReflectionMethod

Básicamente, utilizar algo así y se puede utilizar tanto para generar sus documentos, y para hacer cosas como automóviles filtrado, validación, etc.

en cuanto a la creación de pruebas unitarias, PHPUnit puede generar los automáticamente de sus clases (comprobar sus documentos para más información: http://www.phpunit.de/manual/3.5/en/skeleton-generator.html#skeleton-generator.test

Usted también puede tener phpdocumenter analizar sus etiquetas personalizadas: http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.customtags

Por último, hay un marco por ahí (que yo sepa, estoy seguro de que hay toneladas) que utiliza anotaciones para hacer todo tipo de bondad de descanso (tal vez ahorrando algo de trabajo): http://www.recessframework.org/

esperanza de que ayuda!

Answer 2

Swagger parece prometedor, pero requerirá que su API se exponga de manera compatible ... es bastante agradable, sin embargo, con una consola de prueba, etc. todo integrado ... puede descargar una versión de JavaScript y ejecutar en tu servidor junto con php api.

EDIT: aquí está el enlace, ¿no es cierto tan fácil de encontrar en google si usted no tiene el nombre completo ... lol ... Swagger-UI: https://github.com/wordnik/swagger-ui

Answer 3

Una API REST debe ser totalmente visible y auto-documentado. Solo necesita una URL y todo lo demás vinculado a ella debe describirse a sí mismo. Suena como una utopía, pero es factible.

Por ejemplo, vamos a empezar con un ejemplo de URL stackoverflow como: http://restfuloverflow.com (ilustrativo)

El primero que se hace en un recurso REST es una solicitud de OPCIONES.Siempre hay que incluir un Acepta el encabezado para indicar al servidor para responder al tipo mime más apropiado:

OPTIONS * HTTP/1.1 
Accept: text/html, text/xml, application/json 
Host: restfuloverflow.com 

El servidor debe indicar al cliente en lo que es posible hacer en ese URL:

HTTP/1.1 200 Ok 
Allow: GET, POST, PUT, DELETE, OPTIONS, TRACE, PATCH 

Esta es la API RESTful que le indica que este servicio admite estos métodos. El primero que probará es algo así como la solicitud a continuación. Un usuario que golpea la API con un navegador debería funcionar de manera similar.

GET/HTTP/1.1 
Accept: text/html, text/xml, application/json 
Host: restfuloverflow.com 

continuación, el servidor debe devolver algunos enlaces que apuntan a recursos relacionados, si está disponible:

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> 

una versión HTML debe utilizar <a> enlaces, y las respuestas JSON debe utilizar JSON-Esquema links atributo.

Digamos que el cliente ahora decide que quiere saber qué hacer con las preguntas:

OPTIONS /questions HTTP/1.1 
Host: restfuloverflow.com 
Accept: text/html, text/xml, application/json 

Una posible respuesta podría ser:

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> 

Pues bien, el camarero nos dijo que es posible GET y POST una nueva pregunta. También nos dijo cómo se ve una pregunta en XML al proporcionar un esquema XML. Se podría proporcionar un JSON-SCHEMA para JSON, y en HTML se podría proporcionar un formulario para nuevas preguntas.

Digamos que el usuario quiere obtener las preguntas:

GET /questions HTTP/1.1 
Host: restfuloverflow.com 
Accept: text/html, text/xml, application/json 

A continuación, el servidor responde:

HTTP/1.1 200 Ok 
Content-Type: text/xml 

<?xml version="1.0"> 
<questions> 
    <link href="https://stackoverflow.com/questions/intersting" title="Intersting Questions"/> 
    <link href="https://stackoverflow.com/questions/hot" title="Hot Questions"/> 
</questions> 

Ahora, todo está vinculado de nuevo. La cosa continúa de una manera que el servicio se describe a sí mismo. El Netflix API sigue principios similares, pero carece de algunas características de autodescubrimiento.

This Brazillian Government API se describe a sí mismo usando RDF. Es una de las mejores muestras RESTful que he visto en mi vida. Intenta cambiar .rdf por .xml, .json o .html. (Todo está en portugués, lo siento por eso).

La mejor herramienta para API RESTful en PHP es Respect\Rest. Tiene la mayor parte del flujo de trabajo que he descrito aquí ya iniciado, y vienen nuevas características (todavía está en la versión 0.4x).

El costo de construir un sistema de documentación para aplicaciones RESTful es el mismo que construir una aplicación RESTful. Esta es la razón por la que hay tan pocas herramientas como esa y, por lo general, no son tan buenas.

Answer 4

sé de 3 integraciones de PHP con arrogancia:

• Swagger PHP composer

• Swagger PHP Symfony bundle

• Restler 3.0

Todos deben ayudar a crear automáticamente una arrogancia-sp ec, que te da acceso desde swagger-ui. A continuación, puede generar clientes de API, etc.

Answer 5

Encontré un gran paquete de nodos llamado apidoc que hace un trabajo increíble en RESTfuls de documentación. Permite toneladas de etiquetas específicas de API para hacer con params y cosas por el estilo, pero lo que realmente me vendió son sus formularios de prueba in-doc generados para cada método.

lo uso en mi proyecto esqueleto DevOps en https://github.com/ardkevin84/devops.skel.php-with-docs-metrics, pero se puede ver real de salida en mi proyecto API callloop en https://github.com/ardkevin84/api.callloop. El índice apidoc es build/api-docs/apidoc/index.html

El único inconveniente, si es que lo es, es que, naturalmente, tiene sus propios docblocks. Sin embargo, no choca con los Docblocks 'nativos'. Los bloques apidoc no necesitan preceder a un método, por lo que generalmente los agrupo en la parte superior de mi archivo de punto final donde los otros motores de doc no los asociarán con un documento de clase.

Un subproducto: esto funciona gran con fachadas; Utilizo fachada y fábrica mucho en mis puntos finales, y el analizador apidoc me permite manejar las condiciones de la fachada por separado. En el siguiente ejemplo, 'suscribirse', 'cancelar suscripción' y 'desencadenar' son manejados por un solo punto de entrada, pero están documentados por separado.

Ejemplo: Este bloque de documentación

/** * @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 */

que se requiere para generar esta salida, con la forma de la prueba

importante, si está utilizando estándar de $ _GET con Parámetros de consulta: El paquete que se instala desde el nodo no admite en enpoints como service.php?param=value, pero hay una solicitud de extracción en el repositorio de git en https://github.com/apidoc/apidoc/pull/189 que soluciona esto. Es una solución básica para la plantilla predeterminada. Reparé las pocas líneas en mi paquete de nodos y funciona como un amuleto.

autopromoción desvergonzada: Esto es probablemente mucho más fácil de usar en una compilación automatizada. Eche un vistazo a mi proyecto devops anterior para un kickstart;) Se bifurca de jenkins-php, pero agrega en varios motores de doc y objetivos de trozos para cosas como empujar docs \ metrics generados a una ruta localhost y salida de empaquetado para liberación (zip, tar, etc.)