Cómo instalar y configurar Laravel Enlighten

Enlighten es un nuevo componente para Laravel desarrollado por Duilio Palacios y Jeff Ochoa que te permite generar automáticamente la documentación de tus APIs usando para ello tu suite de pruebas automatizadas.

Así es, Enlighten toma tus clases de prueba y genera la documentación de tus APIs, por lo que no tendrás que preocuparte de añadir un sinfín de docblocks a cada método o crear wikis extensos, con este paquete tendrás tu documentación actualizada de forma rápida y sencilla.

Pre-requisitos

Enlighten requiere PHP 7.3 o superior, así como Laravel en su versión 7 o superior.

Por defecto, Enlighten requiere que tu proyecto use el sistema de control de versiones git.

Instalar Enlighten

Puedes instalar Enlighten usando Composer. Para ello, ve al directorio raíz de tu proyecto y ejecuta desde la terminal:

#
composer require styde/enlighten --dev

Este comando instalará la versión más reciente del paquete; para el momento de escribir esta serie es 0.4.

Si no estás utilizando la característica de auto-descubrimiento de paquetes de Laravel, puedes agregar en tu archivo config/app.php el siguiente proveedor de servicios:

<?php
return [
    //...
    'providers' => [
        // ...
        Styde\Enlighten\Providers\EnlightenServiceProvider::class,
    ]
];

Instalación automática

A partir de Enlighten 0.5, puedes ejecutar php artisan enlighten:install para instalar Enlighten automáticamente, sino puedes hacerlo manualmente siguiendo estos 3 pasos:

Publicar assets (instalación manual)

Luego debes publicar los assets (CSS, JavaScript) en la carpeta public de tu proyecto, ejecutando:

#
php artisan vendor:publish --tag=enlighten-build

Además, también puedes publicar su archivo de configuración y las vistas para una mayor personalización:

php artisan vendor:publish --tag=enlighten-config
php artisan vendor:publish --tag=enlighten-views

Este último paso es opcional.

Agregar trait `EnlightenSetup` (instalación manual)

Finalmente, en tu archivo tests/TestCase.php, agrega el trait EnlightenSetup y llama a setUpEnlighten() dentro del método setUp, por ejemplo:

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Styde\Enlighten\Tests\EnlightenSetup;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication, EnlightenSetup;

    protected function setUp(): void
    {
        parent::setUp();

        $this->setUpEnlighten();
    }
}

No olvides importar y usar el trait Styde\Enlighten\Tests\EnlightenSetup.

Configuración de la base de datos

Enlighten necesita su propia base de datos y conexión para registrar y mostrar la información de tu suite de pruebas. Puedes configurar esta base de datos de dos formas:

Usando la convención

Si tu proyecto cumple con las siguientes convenciones:

- Una base de datos por defecto (no sqlite) para el entorno local.
- Una base de datos (no sqlite) para el entorno de pruebas con el sufijo _test o _tests.

Solo necesitarás crear una nueva base de datos con el mismo nombre de tu base de datos local, más el sufijo _enlighten.

Por ejemplo, si tu base de datos local es my_db y la de tus pruebas es my_db_tests, deberás crear una base de datos llamada my_db_enlighten.

Recuerda que tu base de datos local está configurada en el archivo .env, mientras que el nombre de la base de datos de pruebas se configura en phpunit.xml.

Agregando una nueva conexión

Si no sigues la convención anterior, puedes crear una nueva base de datos con el nombre de tu preferencia y agregar una nueva conexión en el archivo config/database.php con el nombre enlighten, por ejemplo:

<?php

//...
'enlighten' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => 'my_enlighten_database',
    // ...
],

Ejecutar migraciones

Una vez que tengas creada y configurada la base de datos, puedes ejecutar tus migraciones por medio de Artisan:

#
php artisan enlighten:migrate

También puedes ejecutar:

php artisan enlighten:migrate:fresh

Generando la documentación

Para generar la documentación solo debes ejecutar:

php artisan enlighten

Deberías ver una salida como la siguiente:

En el siguiente tutorial aprenderemos más sobre este componente.

Recuerda configurar la variable de entorno APP_URL de tu proyecto.

Material relacionado

Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.

Publicado por: Ambar Quintana

Programador en Laravel y SQL

Composer Enlighten PHPUnit TestCase Tests

Lección siguiente Personaliza tu documentación con Laravel Enlighten