Enlighten es un paquete con una interfaz amigable que te permite documentar tus APIs automáticamente a través de su suite de pruebas, una vez que tengas instalado y configurado este paquete, usarlo te resultará muy sencillo.
Usando Enlighten
Después que el paquete ha sido instalado y configurado en tu proyecto, ejecuta tus pruebas como de costumbre y… ¡Listo!. Podrás ver toda la documentación de tu API visitando /enlighten.
Por ejemplo, si estás usando php artisan serve, deberás dirigirte a http://127.0.0.1:8000/enlighten.
Styde ha creado una demo basada en la aplicación del Curso Crea un Panel de Control para demostrarte el funcionamiento del paquete. Puedes descargarla aquí. Ten en cuenta que hemos dejado algunas pruebas fallando a propósito para que veas cómo se comporta Enlighten en esos escenarios.
Interfaz de Enlighten
Al visitar /enlighten lo primero que encontrarás es su Dashboard, el cual te mostrará la(s) rama(s) donde la documentación fue generada, la fecha en que se ejecutaron las pruebas, el número de pruebas exitosas / totales y un enlace para acceder a cada variante ejecutada:
Enlighten guarda el nombre de la rama de git de tu proyecto, así como el Hash del último commit y si se han detectado cambios que no se han agregado como commit a git o no. Enlighten guarda solo el estado de la última ejecución de pruebas para cada variante de rama / commit y estado.
En el menú, aparecerán las diferentes Áreas de tu proyecto, cada área representará típicamente una suite de pruebas (Api, Feature, Unit, etc.) así como los Módulos (Users, Professions, Other Modules, etc.) que hayas configurado en config/enlighten.php:
Al acceder a la documentación, podrás ver una serie de «paneles»; cada panel representa un módulo configurado previamente en config/enlighten.php y contiene el número de pruebas exitosas / totales del panel y un listado.
En el listado de cada panel verás tus clases de pruebas representadas como Grupos de Ejemplos. Estos grupos estarán acompañados de un icono que te indicará si todas las pruebas dentro de dicho grupo fueron exitosas o, por el contrario, si contienen al menos una prueba fallida o con advertencia:
Por ejemplo, dentro del módulo «Users» podemos ver 57 pruebas exitosas. Mientras que el módulo Professions solo tiene 2 pruebas exitosas de 5. Gracias a los iconos puedes ver rápidamente cual o cuales grupos requieren tu atención.
Al hacer clic a un grupo de ejemplos podrás ver sus métodos, representados en Enlighten como Ejemplos, junto con la petición o peticiones de cada ejemplo:
Y haciendo clic en la prueba tendrás esta información mucho más detallada, incluyendo un preview del contenido que te mostraría el navegador:
Exportando la documentación
Enlighten también te permite exportar la documentación generada en archivos de HTML estáticos, usando el comando:
php artisan enlighten:export
Este comando te pedirá que especifiques la rama (branch) de la documentación generada que deseas exportar, el directorio de exportación y la URL base para ver los archivos exportados.
Por ejemplo, si defines public/docs como directorio de exportación y /docs como URL base de los archivos exportados, al usar php artisan serve podrás acceder a ellos visitando http://127.0.0.1:8000/docs/index.html.
Material relacionado
Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.
Lección anterior Personaliza tu documentación con Laravel Enlighten