README

无缝的包，用于文档化你的Laravel API。

无需为每个API方法添加无穷无尽的docblocks，也无需维护数十个readme文件，或编写详尽的wiki来保持API的文档化并同步代码库！

通过从你的测试套件自动生成文档，美化你的Laravel应用程序，这样你的文档将始终与你的应用程序当前版本保持更新。

如果你已经投入了大量时间开发和测试你的API，你不需要花费同样多的时间来文档化它，我们会为你做这件事，你应得的！

兼容性

Enlighten与Laravel 7.28及以后版本兼容，并需要PHP 7.3及以上版本。

你可以成为这个项目的一部分

介绍Laravel Enlighten

安装组件后，运行 php artisan enlighten，就这样！你可以在以下URL找到整个API文档： /enlighten/

用法

完成安装过程后，运行以下命令执行你的Laravel测试

php artisan enlighten

你可以传递通常传递给 php artisan test 的任何选项，包括Laravel 8及以后版本中可用的 --parallel 选项！

现在访问 /enlighten/ 以浏览文档。

运行 php artisan enlighten:export 将文档导出为静态文件！

演示项目

按照我们的3分钟安装指南，在你的应用程序中查看Enlighten的实际应用（你不需要修改你的测试！）

或者，按照其README中的说明安装我们的演示项目。

安装

安装Enlighten只需3个步骤！

步骤1：Composer Require

使用Composer将包作为 dev 依赖项引入

composer require styde/enlighten --dev

如果你没有使用Laravel包自动发现功能，请将以下服务提供者添加到 config/app.php

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

步骤2：安装Enlighten

运行 php artisan enlighten:install 以自动安装和设置Enlighten，否则请遵循手动设置部分的说明。

步骤3：数据库设置

按照以下说明创建和配置Enlighten数据库

Enlighten需要一个自己的数据库以及数据库连接来记录和保存从你的测试套件生成的文档。

如果你使用以下约定

本地环境中的非sqlite默认数据库（例如 my_db）
带有 _test 或 _tests 后缀的非sqlite测试环境数据库（例如 my_db_tests）

只需添加一个使用默认数据库相同名称的新数据库，并在名称后添加 _enlighten 后缀，例如

# .env
# If your local database is:
DB_NAME=my_default_database
#
# phpunit.xml
# And your test database is:
# <env name="DB_DATABASE" value="my_default_database_tests"/>
#
# Then Enlighten will use a third database automatically:
# my_default_database_enlighten

如果你没有遵循上述约定，只需在 config/database.php 中添加一个名为 enlighten 的新连接条目并配置你的自定义设置

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

为了防止在使用Laravel包含的数据库迁移特性或使用SQLite运行测试时信息被删除或未持久化，对Enlighten使用不同的连接和数据库非常重要。

使用php artisan enlighten:migrate运行包迁移。

您还可以使用：php artisan enlighten:migrate:fresh来刷新迁移。警告：这将同时删除自动生成的文档！

手动设置

如果您没有运行php artisan enlighten:install或收到错误消息，您可以按照以下说明手动设置Enlighten

使用Artisan将包资产（CSS、JavaScript）发布到公共文件夹

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

可选地，您还可以发布配置文件和视图以进行更多定制。

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

第三步：导入特性Styde\Enlighten\Tests\EnlightenSetup并在您的TestCase的setUp方法中调用$this->setUpEnlighten()，例如

<?php

namespace Tests;

use Styde\Enlighten\Tests\EnlightenSetup;

class TestCase extends \Tests\TestCase
{
    use EnlightenSetup;

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

        $this->setUpEnlighten();
    }
}

注意：请记住包含并使用特性Styde\Enlighten\Tests\EnlightenSetup。

可选配置

要“分组”您的测试类为“模块”，您可以使用正则表达式查找所有与给定模式或模式匹配的类

// config/enlighten.php
[
    'modules' => [
        [
            'name' => 'Users',
            'pattern' => ['*Users*']
        ],
        [
            'name' => 'Projects',
            'pattern' => ['*Projects*', '*Project*']
        ],
        [
            'name' => 'Other Modules',
            'pattern' => ['*'],
        ],
    ]
];

您可以在末尾添加一个“通配符”组以包含所有那些与任何其他模式不匹配的文件，否则Enlighten会自动为您这样做。

排除测试类从文档中

如果您想包含所有测试类和方法在您的文档中，您可以跳过此步骤，否则，您可以将以下键添加到/config/enlighten.php文件中

[
    'tests' => [
        // Add expressions to ignore test class names and test method names.
        // i.e. Tests\Unit\* ignores all tests in the Tests\Unit\ suite,
        // validates_* ignores all tests that start with validates_.
        'ignore' => [
            'method_that_will_be_ignored',
        ],
    ],
];

您还可以通过在任意类或方法上添加@enlighten {"ignore": true}注释来忽略类和方法，例如

/**
 * @enlighten {"ignore": true}
 */
class IgnoreClassWithAnnotationTest extends TestCase
{
    use RefreshDatabase;

    /**
     * @test
     * @enlighten {"ignore": true}
     */
    function does_not_export_test_methods_with_the_enlighten_ignore_annotation()
    {
        $this->assertExampleIsNotCreated();
    }
}

如果您想执行相反的操作（通过配置选项包括之前已忽略的类），只需在该类或方法上添加@enlighten注释即可

/**
 * @enlighten
 */
class IncludeMethodWithAnnotationTest extends TestCase
{
    /**
     * @test
     * @enlighten
     */
    function export_test_method_with_the_enlighten_annotation_even_if_its_ignored_in_the_config()
    {
        $this->assertExampleIsCreated();
    }
}

注意：注释优先于配置选项。

自定义标题和描述

如果您想对类和方法的标题有更多控制，或为每个组或示例添加描述，您可以在您的测试类和方法中添加以下注释

/**
 * @title User Module
 *
 * or if you prefer:
 *
 * @testdox User Module
 *
 *  and you can also use:
 *
 * @description Manage all the user-related petitions.
 **/
class UsersTest extends TestCase {

    /**
     *
     * @testdox Create Users
     *
     * @description Register a new user via POST request. API credentials must be provided.
     **/
    public function testRegisterNewUsers()
    {
        $this->assertTrue(true);
    }
}

隐藏视图中的部分

您可以通过配置隐藏整个UI部分

// config/enlighten.php
return [
    // Add values to this array if you want to hide certain sections from your views.
    // For valid sections see \Styde\Enlighten\Section
    'hide' => [
        //
    ],
];

记录您的内部API（类、方法和函数）

您还可以通过使用Enlighten::test()外观创建从单元测试的代码片段，这将允许您将代码示例添加到文档中。

use Styde\Enlighten\Facades\Settings;

class CalcTest extends TestCase
{
    /**
     * @test 
     * @testdox Sum two numbers
     * @description Use the Calc `sum` static method to sum two numbers.
    **/
    public function can_sum_two_numbers()
    {
        $result = Settings::test(function () {
            $a = 1;
            $b = 2;
            return Calc::sum($a, $b);
        });
          
        $this->assertSame(3, $result);
    }
}

可选地，您可以使用enlighten()辅助函数而不是Enlighten::test()外观。

将文档导出为静态HTML文件

从v0.4开始，您可以使用Artisan为您的文档生成静态文件

php artisan enlighten:export

您可以选择自定义导出目录和用于静态文件的基本URL。

自定义介绍页面

要自定义仪表板页面的内容，您可以在项目的根路径中添加一个ENLIGHTEN.md markdown文件。该文件的内容将覆盖此包提供的默认页面。

社区链接

英文

西班牙语

使用Laravel Enlighten自动生成应用程序文档（Styde.net）

德语

Johannes Arndt：Laravel Enlighten - 记录您的Laravel API的无缝包（Laravel Meetup DACH）

致谢

许可协议

MIT许可（MIT）。有关更多信息，请参阅许可文件

styde / enlighten

维护者

详情