API REST de documentación automática en PHP

12 minutos de lectura

phpDocumentor parece ser el estándar para documentar el 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 de una API REST; IE, puntos de entrada accesibles desde el exterior en los que estaría interesado un usuario final de su sistema, en lugar de documentar todas las clases internas y demás, algo que solo interesa a los desarrolladores de la API.

Estoy buscando algo en lo que pueda decir, hey, este método aquí es accesible externamente a través de REST en esta URL, aquí están los argumentos GET o POST que necesita, es compatible con los 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 unitarias básicas, etc.

  • Relacionado con este y este otro, aunque este último parece engañar al primero.

    – Patricio

    27 de septiembre de 2012 a las 16:06


Conozco 3 integraciones de PHP con swagger:

Todo debería ayudar a crear automáticamente una especificación de swagger, que le da acceso desde swagger-ui. Luego puede generar clientes api, etc.

  • Si usa Symfony 2.x, el paquete de documentos API de Nelmio también debe estar marcado: github.com/nelmio/NelmioApiDocBundle

    – Nikolá Petkanski

    11 de febrero de 2013 a las 14:04


  • Uso swagger PHP (de composer) para documentar nuestra API de trabajo api.buto.tv/docs . Funciona muy bien.

    – Jujhar Singh

    12 de abril de 2013 a las 11:24

Una API RESTful debe ser totalmente detectable y autodocumentada. Solo necesita una URL y todo lo demás vinculado a ella debe describirse a sí mismo. Suena a utopía, pero es factible.

Por ejemplo, comencemos con una URL de muestra similar a stackoverflow: http://desbordamientodescanso.com (ilustrativo)

Lo primero que hace en un recurso RESTful es una solicitud de OPCIONES. Siempre debe incluir un encabezado Aceptar para indicarle al servidor que responda al tipo de MIME más apropiado:

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

El servidor debe instruir al cliente sobre lo que se puede hacer en esa URL:

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

Esta es la API RESTful que le dice que este servicio admite estos métodos. El primero que intentará es algo como la solicitud a continuación. Un usuario que accede a 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

El servidor debería devolver algunos enlaces que apuntan a recursos relacionados, si están disponibles:

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

<?xml version="1.0">
<qa>
    <link href="https://stackoverflow.com/questions" title="Questions"/>
    <link href="https://stackoverflow.com/tags" title="Tags"/>
    <link href="https://stackoverflow.com/users" title="Users"/>
</qa>

Una versión HTML debería usar <a> los enlaces y las respuestas JSON deben usar JSON-Schema 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>

Bueno, el servidor nos dijo que es posible OBTENER y PUBLICAR 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 preguntas:

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

Entonces 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="http://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. los API de Netflix sigue principios similares, pero carece de algunas funciones de detección automática.

Esta API del gobierno brasileño se describe a sí mismo usando RDF. Es una de las mejores muestras RESTful que he visto. Intente cambiar .rdf a .xml, .json o .html. (Todo está en portugués, perdón por eso).

La mejor herramienta para las API RESTful en PHP es Respeto\Descanso. Tiene la mayor parte del flujo de trabajo que he descrito aquí ya iniciado, y están llegando nuevas funciones (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. Es por eso que hay tan pocas herramientas como esa, y por lo general no son tan buenas.

  • He votado -1. La razón es simple: la pregunta es qué se puede usar para documentar el comportamiento de una API expuesta a través del servicio RESTful. No es cómo estructurar los servicios REST. Actualmente necesito esa solución y esta respuesta no me ayuda en absoluto.

    – Nikolá Petkanski

    11 de febrero de 2013 a las 14:07

  • La pregunta es sobre la documentación automática, lo que significa un software que puede documentarse a sí mismo. Necesita consistencia estructural para esto. Todavía puede hacerlo parcialmente (la mayoría de los servicios REST no implementarán OPCIONES) y aún así obtener el beneficio de la documentación automática. No conozco herramientas externas genéricas para documentar servicios REST genéricos.

    – alganeta

    14 de febrero de 2013 a las 18:52


  • -1 No responde la pregunta. La pregunta no descarta las API de descanso descubiertas automáticamente. La pregunta es sobre la generación de documentación automática. Al ser detectable automáticamente, aún necesita una cantidad decente de documentación sobre las funciones que implementa la API y cómo se deben interpretar los datos para poder seguir los enlaces. En su ejemplo con restfuloverflow, el desarrollador desea agregar comentarios automáticos. Sin saber qué recurso significa “comentario”, no hay remedio. El texto “Agregar comentario” no le dice al código lo que significa.

    –Peter Nordlander

    9 de enero de 2014 a las 19:28

  • Otra razón para -1 esta respuesta es que está hablando de servicios ReST basados ​​en HATEOAS. ReST es un patrón de diseño, mientras que HATEOAS es una versión extremadamente rígida de ReST con mucha integración de encabezados, detección automática, etc. ¡No confundas ReST y HATEOAS ya que uno puede vivir fuera del otro!

    – Mathieu Dumoulin

    15 de abril de 2015 a las 17:14

Avatar de usuario de Kevin Ard
kevin ard

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

Lo uso en mi proyecto de esqueleto devops en https://github.com/ardkevin84/devops.skel.php-with-docs-metricspero puedes ver actual salida en mi proyecto callloop api 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, toma sus propios bloques de documentación. 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 documentos no los asociarán con un documento de clase.

Un subproducto: esto funciona estupendo con fachadas; Uso mucho la fachada y la fábrica en mis puntos finales, y el analizador apidoc me permite manejar las condiciones de la fachada por separado. En el ejemplo a continuación, ‘suscribir’, ‘cancelar suscripción’ y ‘activar’ son manejados por un solo punto de entrada, pero están documentados por separado.

Ejemplo: Este 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
 */

se requiere para generar esta salida, complete con el formulario de prueba
salida DOCBLOQUE

importante, si está utilizando $_GET estándar con parámetros de consulta: El paquete que se instala desde el nodo no admite puntos como service.php?param=valuepero hay una solicitud de extracción en el repositorio de git en https://github.com/apidoc/apidoc/pull/189 que aborda esto. Es una solución básica a la plantilla predeterminada. Parcheé las pocas líneas en mi paquete de nodo y funciona de maravilla.

autopromoción desvergonzada: Esto es probablemente mucho más fácil de usar en una compilación automatizada. Echa un vistazo a mi proyecto devops anterior para un buen comienzo;) Está bifurcado de jenkins-php, pero agrega varios motores de documentos y objetivos de código auxiliar para cosas como enviar documentos/métricas generados a una ruta de host local y empaquetar la salida para su lanzamiento (zip, tar, etc.) )

Swagger parece prometedor, pero requerirá que su API se exponga de manera compatible… sin embargo, es bastante bueno, con una consola de prueba, etc., todo integrado… puede descargar una versión de javascript y ejecutarla en su servidor junto con la API de php.

EDITAR: aquí está el enlace, no es tan fácil de encontrar en Google si no tienes el nombre completo… lol… Swagger-UI: https://github.com/wordnik/swagger-ui

Avatar de usuario de Ian Selby
Ian Selby

Lo más fácil de hacer es usar un analizador/tokenizador docblock. Hay un par de ellos por ahí (en breve pondré el mío), pero básicamente pueden examinar el docblock y tokenizar cualquier etiqueta de docblock personalizada (o no personalizada). He usado esto dentro de un marco mío para definir los tipos de ayuda de vista a través de una etiqueta llamada “@helperType”.

Como dije, hay muchos por ahí, pero aquí está el mío para que comiences: https://github.com/masterexploder/DocumentingReflectionMethod

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

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

También puede hacer que phpdocumenter analice sus etiquetas personalizadas: http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.customtags

Finalmente, existe un marco (que yo sepa, estoy seguro de que hay toneladas) que usa anotaciones para hacer todo tipo de bondades relajantes (tal vez ahorrándose algo de trabajo): https://github.com/receso/receso

¡Espero que ayude!

  • También podría querer ver Vanity Docs (un amigo mío lo está desarrollando). Aún no publicado, pero debería estarlo pronto: twitter.com/#!/vanitydoc

    – Ian Selby

    15 de marzo de 2011 a las 18:34

  • De hecho, he visto el marco del receso, parece un poco agradable. En este momento he estado usando Kohana.

    – Greywire

    15 de marzo de 2011 a las 22:23

  • También estoy usando anotaciones (a través de Addendum) para cosas de la base de datos y algunas validaciones. Había considerado implementar mi propio generador de documentación basado en lo que ya tengo, pero pensé que alguien ya debería haberlo hecho, para documentar los servicios web REST. En cuanto a las pruebas, tal vez prueba unitaria no era el término correcto, sino prueba funcional… IE para probar la API REST en lugar de probar clases individuales. Creo que miré las etiquetas personalizadas en phpdocumentor en un momento y parecía un poco arcano de usar, tal vez lo revisaré nuevamente (nuevamente me pregunto por qué no hay actualizaciones en tanto tiempo).

    – Greywire

    15 de marzo de 2011 a las 22:29

  • Finalmente, definitivamente revisaré lo tuyo … 🙂 (hmm, no estoy seguro de por qué el límite en el tamaño de los comentarios … 🙂

    – Greywire

    15 de marzo de 2011 a las 22:29

  • También podría querer ver Vanity Docs (un amigo mío lo está desarrollando). Aún no publicado, pero debería estarlo pronto: twitter.com/#!/vanitydoc

    – Ian Selby

    15 de marzo de 2011 a las 18:34

  • De hecho, he visto el marco del receso, parece un poco agradable. En este momento he estado usando Kohana.

    – Greywire

    15 de marzo de 2011 a las 22:23

  • También estoy usando anotaciones (a través de Addendum) para cosas de la base de datos y algunas validaciones. Había considerado implementar mi propio generador de documentación basado en lo que ya tengo, pero pensé que alguien ya debería haberlo hecho, para documentar los servicios web REST. En cuanto a las pruebas, tal vez prueba unitaria no era el término correcto, sino prueba funcional… IE para probar la API REST en lugar de probar clases individuales. Creo que miré las etiquetas personalizadas en phpdocumentor en un momento y parecía un poco arcano de usar, tal vez lo revisaré nuevamente (nuevamente me pregunto por qué no hay actualizaciones en tanto tiempo).

    – Greywire

    15 de marzo de 2011 a las 22:29

  • Finalmente, definitivamente revisaré lo tuyo … 🙂 (hmm, no estoy seguro de por qué el límite en el tamaño de los comentarios … 🙂

    – Greywire

    15 de marzo de 2011 a las 22:29

¿Ha sido útil esta solución?