README

Scribe 的测试驱动文档方法。

好处

更好的工作流程，您不必在控制器中编写参数的 docblock 注释，而可以自动从执行的测试中生成文档。
控制器中注释杂乱较少。仍需要一些注释（如 @group），但可以将注释放在测试类中。
通过在测试方法中放置 docblocks，可以轻松记录继承自基控制器或 traits 的控制器方法。
遵循“未经测试即不存在”的原则。这确保了您的文档和测试是一致的。
由于来自执行的测试，因此可以轻松记录响应，而不依赖于有时由于数据库状态不一致而导致错误的响应调用。

安装和设置

步骤 1：Composer 需求

composer require --dev ajcastro/scribe-tdd

步骤 2：在 TestCase 中使用 ScribeTddSetup trait

use AjCastro\ScribeTdd\Tests\ScribeTddSetup;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication, ScribeTddSetup;

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

        $this->setUpScribeTdd();
    }
}

步骤 3：设置必要的策略

    'strategies' => [
        'metadata' => [
            // ...
            AjCastro\ScribeTdd\Strategies\Metadata\GetFromDocBlocksFromScribeTdd::class,
        ],
        'urlParameters' => [
            // ...
            AjCastro\ScribeTdd\Strategies\UrlParameters\GetFromUrlParamTagFromScribeTdd::class,
        ],
        'queryParameters' => [
            // ...
            AjCastro\ScribeTdd\Strategies\QueryParameters\GetFromTestResult::class,
            AjCastro\ScribeTdd\Strategies\QueryParameters\AddPaginationParametersFromScribeTdd::class,
            AjCastro\ScribeTdd\Strategies\QueryParameters\GetFromQueryParamTagFromScribeTdd::class,
        ],
        'headers' => [
            // ...
            AjCastro\ScribeTdd\Strategies\Headers\GetFromHeaderTagFromScribeTdd::class,
        ],
        'bodyParameters' => [
            // ...
            AjCastro\ScribeTdd\Strategies\BodyParameters\GetFromTestResult::class,
            AjCastro\ScribeTdd\Strategies\BodyParameters\GetFromBodyParamTagFromScribeTdd::class,
        ],
        'responses' => [
            // ...
            AjCastro\ScribeTdd\Strategies\Responses\GetFromTestResult::class,
            AjCastro\ScribeTdd\Strategies\Responses\UseResponseTagFromScribeTdd::class,
            AjCastro\ScribeTdd\Strategies\Responses\UseResponseFileTagFromScribeTdd::class,
        ],
        'responseFields' => [
            // ...
            AjCastro\ScribeTdd\Strategies\ResponseFields\GetFromResponseFieldTagFromScribeTdd::class,
        ],
    ],

您可以选择禁用现有的默认策略，或者只是添加这些策略，这样您可以同时享受两个世界。

使用方法

步骤 1：创建并运行测试

只需创建您常用的 phpunit 测试并运行它们。这将生成用于稍后生成 scribe 文档的必要文件。

phpunit

步骤 2：运行 scribe:generate

请确保使用 --force 以删除缓存输出。

php artisan scribe:generate --force

步骤 3：Gitignore 自动生成的 json 文件

将以下内容添加到您的 .gitignore 以忽略自动生成的 json 文件。您应该提交您创建的文件，那些以 -@.json 结尾的文件，以便在生成 api 文档时始终应用。

storage/scribe-tdd/*/*
!storage/scribe-tdd/*/*-@.json

步骤 4：删除自动生成的文件（可选）

当您运行 phpunit 测试时，它会创建很多文件。您可以通过运行以下命令删除这些文件，这样就不会删除您创建的文件。

php artisan scribe:tdd:delete

示例用法

这是一个使用 tdd 方法的示例项目：ajcastro/TheSideProjectAPI#1

致谢

此包受 Enlighten 启发。

ajcastro / scribe-tdd

维护者

详细信息