En esto Programando con la serie Yii2, Estoy guiando a los lectores en el uso del Marco Yii2 para PHP. También te puede interesar mi Introducción al marco Yii, que revisa los beneficios de Yii e incluye una descripción general de las novedades de Yii 2.x.
¡Bienvenido! Recientemente, escribí sobre la creación de API REST para su aplicación Yii y las API personalizadas expandidas para nuestra aplicación de serie de inicio, Meeting Planner.
En el tutorial de hoy, te presentaré la extensión apidoc de Yii, que genera automáticamente la documentación navegable para tu código. Lo usaré para generar documentación de API para el Planificador de reuniones.
Empezando
Instalar apidoc es fácil. Como se muestra arriba, solo agregas el paquete usando composer.
Además de generar documentación a partir de código, también es capaz de generar documentación desde markdown y transformarla en archivos PDF..
Por ejemplo, hay documentación de Yii Framework, documentación de código típico:
Y, aquí está la Guía Yii2, que creo que se genera desde markdown aquí y se integra con la documentación del código para una fácil navegación:
Aquí está la sintaxis de documentación que soporta apidoc; esta basado en phpdoc.
Irónicamente, la documentación para apidoc aún no está completa, pero es bastante fácil de usar para la documentación automática básica..
Generación de documentación API
Si ha seguido mi serie de inicio, sabe que estoy creando una API extensa para soportar aplicaciones móviles, etc. Apidoc es la forma ideal para que yo mantenga una documentación dinámica automatizada para ella..
Ciertamente, hay muchos otros servicios web que te ayudan a documentar tu API, pero descubrí que el apidoc de Yii funcionó bien para mis necesidades, y aprecié el tema de estilo phpdoc que usan.
El uso de un estilo de comentarios estándar hace que sea probable que otros servicios puedan compilar fácilmente la documentación del código del Planificador de reuniones si alguna vez quisiera usarlos..
Creación de bloques de comentarios
Básicamente, crea comentarios dentro de su código que utiliza apidoc para construir su documentación. Se describe en la guía de estilo de codificación Yii..
Coloca un bloque de comentarios en la parte superior de cada archivo como este:
Y coloca un bloque de comentarios sobre cada controlador o definición de modelo:
/ ** * UserTokenController proporciona la funcionalidad de API para el registro, eliminar y verificar * * @autor Jeff Reifman * @since 0.1 * / class UserTokenController extiende el controlador
Luego, coloca un bloque de comentarios detallado sobre cada método, que incluye parámetros, valores de retorno y excepciones:
/ ** * Registre un nuevo usuario con un Oauth_token social externo * * @param string $ firma el hash generado con app_secret * @param string $ app_id en el encabezado, el ID de la aplicación secreta compartida * @param string $ correo electrónico en el encabezado, dirección de correo electrónico * @param string $ firstname in header, primer nombre * @param string $ lastname in header, apellido * @param string $ oauth_token in header, el token devuelto de Facebook durante OAuth para este usuario * @param string $ source in header, la fuente de la que proviene el $ oauth_token, por ejemplo, 'facebook' por ejemplo [$ oauth_token] * @return obj $ identityObj con user_id y user_token * @throws Excepción aún no implementada * / función pública actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")
Debe seguir el diseño prescrito como se describe para alimentar apidoc correctamente.
Uso de argumentos de marcador de posición para la documentación de la API
El equipo de Yii desarrolló apidoc para generar documentación de código. Sin embargo, como escribí en Securing Your API, todos, excepto el argumento de la firma de hash, se han movido a los encabezados http. Estos son invisibles al apidoc. Por lo tanto, para generar la documentación de la API, decidí utilizar una solución alternativa.
Como puede ver, incluyo argumentos ficticios en los métodos y luego especifico en los comentarios que estos se envían como encabezados o "en encabezado".
* @param string $ firma el hash generado con app_secret * @param string $ app_id en el encabezado, el id de la aplicación secreta compartida * @param string $ correo electrónico en el encabezado, dirección de correo electrónico * @param string $ firstname en el encabezado, nombre * @param cadena $ lastname en el encabezado, apellido
Mientras los valores predeterminados estén incluidos en las definiciones de funciones, no se hará ningún daño real:
En un momento, verá cómo esto funciona generalmente para la documentación de la API, incluso si no es un estilo de codificación óptimo.
Continuemos con el uso de apidoc para generar la documentación..
Generando la Documentación
Puede revisar los comandos apidoc ejecutándolo sin argumentos:
$ ./vendor/bin/apidoc Esta es la versión 2.0.10 de Yii. Los siguientes comandos están disponibles: - api Genera la documentación de la API de clase. api / index (predeterminado) Archivos de documentación de la API de Renders: guía Este comando puede representar la documentación almacenada como archivos de rebajas, como la guía / índice de yii (predeterminado) Archivos de documentación de la API de Renders: ayuda Proporciona información de ayuda sobre los comandos de la consola. ayuda / índice (predeterminado) Muestra los comandos disponibles o la información detallada. Para ver la ayuda de cada comando, ingrese: ayuda apidoc
Usaré la opción api, y aquí están las configuraciones que puedes hacer:
$ ./vendor/bin/apidoc help api DESCRIPCIÓN Archivos de documentación de la API de Renders USAGE apidoc api [… Opciones…] - sourceDirs (requerido): array $ sourceDirs - targetDir (requerido): string $ targetDir OPTIONS --appconfig: ruta de acceso del archivo de configuración de la aplicación personalizada de string. Si no se establece, se utiliza la configuración predeterminada de la aplicación. --color: booleano, 0 o 1 para habilitar el color ANSI en la salida. Si no se establece, el color ANSI solo se habilitará para los terminales que lo admiten. --excluir: cadena | archivos de matriz para excluir. --guide: cadena url donde se ubican los archivos de la guía --guidePrefix: prefijo de la cadena (por defecto es 'guía-') que precede a todos los nombres de los archivos de la guía. --help, -h: boolean, 0 o 1 para mostrar información de ayuda sobre el comando actual. --interactive: boolean, 0 o 1 (predeterminado en 1) si se ejecuta el comando de forma interactiva. --pageTitle: título de la página de cadena --template: plantilla de cadena (predeterminada a 'bootstrap') para usar para renderizar
Para generar mi documentación API, cuyo directorio también es api, Haré lo siguiente:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = MeetingPlanner TargetDirectory ya existe. ¿Exagerar? (sí | no) [sí]: sí Buscando archivos para procesar ... listo. Cargando datos apidoc de caché ... hecho. Buscando archivos actualizados ... hecho. 8 archivos para actualizar. Procesando archivos ... hecho. Actualización de referencias cruzadas y backlinks ... hecho. Procesamiento de archivos: hecho. generando archivos de índice de extensión ... hecho. generando índice de búsqueda ... hecho. Se han registrado 35 errores en api / web / docs / errors.txt Se han registrado 214 advertencias en api / web / docs / warnings.txt
Como no he terminado de comentar todo el árbol, se generan errores y advertencias. La mayoría de las veces se ven algo como esto:
Array ([0] => Array ([line] => 31 [file] => api / controllers / ParticipantController.php [message] => El comportamiento de los métodos no tiene un padre que heredar en api \ controllers \ ParticipantController.) [1 ] => Array ([line] => 32 [file] => api / controllers / PlaceController.php [message] => Los comportamientos del método no tienen un padre que heredar en api \ controllers \ PlaceController.)
Navegando por la documentación
Publicando la documentación en la línea de comando apidoc anterior para / api / web / docs significa que puede navegar por la documentación del planificador de reuniones desde la web.
Por ejemplo, aquí está el UserTokenController:
Aquí está el método actionRegister () que muestra los comentarios de parámetros reflejados con el en el encabezado información.
Aquí está la documentación del MeetingController:
Y, aquí está el método actionMeetingplacechoices ():
Como puede ver, esto es extremadamente útil para compartir una API con programadores de terceros en tiempo real a medida que entrega el código. El gran beneficio es que elimina la necesidad de mantener manualmente la documentación de la API por separado..
Cada vez que puedes eliminar una tarea para un inicio, es una gran victoria..
Mirando hacia el futuro
Espero que hayas visto un poco del poder de la extensión apidoc de Yii2. Puede usarlo para mantener la documentación de todo su código, y también lo alienta a mantenerse al día con los comentarios, que haré más de ahora.
Si tiene alguna pregunta o comentario, por favor publíquelo en los comentarios. Si desea mantenerse al día con mis futuros tutoriales de Envato Tuts + y otras series, visite la página de mi instructor o siga a @reifman. Definitivamente echa un vistazo a mi serie de inicio y Meeting Planner.
enlaces relacionados
Yii2 API Doc (GitHub)
Programación con Yii2: Construyendo una API RESTful (Envato Tuts +)
Construyendo su inicio con PHP: Construyendo una API RESTful (Envato Tuts +)
Share
Lo que vas a crear
Accentsconagua
