扩展包 Laravel-compass 使用笔记

由于前几天刚翻译了关于laravel-compass扩展文章，对于此扩展包有很大的兴趣，该扩展包可以根据laravel项目的路由自动生成对应的API测试调用方法(类似Postman)和API文档。当然具体介绍可以查看davidhsianturi/laravel-compass

如何使用该扩展包

通过composer引入该扩展包

composer require davidhsianturi/laravel-compass --dev

然后使用命令:

php artisan compass:install

此命令在config目录下生成compass.php配置文件

return [
    /*
    |--------------------------------------------------------------------------
    | Compass Path
    |--------------------------------------------------------------------------
    |
    | 这是访问compass的路由路径，你可以根据自己的喜好修改路由路径 
    |
    */

    'path' => env('COMPASS_PATH', 'compass'),

    /*
    |--------------------------------------------------------------------------
    | Laravel Routes
    |--------------------------------------------------------------------------
    |
    | 这是将为请求列表过滤的路由规则。使用*作为通配符以匹配任何字符。
    | 注意以下数组“exclude”必须由路由名称引用。
    | “ base_uri”是一个字符串值，用于对路由进行分组比较。
    |
    */

    'routes' => [
        'domains' => [
            '*',
        ],

        'prefixes' => [
            '*',
        ],

        'exclude' => [
            'compass.*',
            'debugbar.*',
        ],

        'base_uri' => '*',
    ],

    /*
    |--------------------------------------------------------------------------
    | Compass Storage Driver
    |--------------------------------------------------------------------------
    |
    | 此配置选项决定了存储驱动程序，它将用于存储您的API调用和路由。
    | 此外，您可以选择特定驱动程序。
    |
    */

    'driver' => env('COMPASS_DRIVER', 'database'),

    'storage' => [
        'database' => [
            'connection' => env('DB_CONNECTION', 'mysql'),
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | API Documentation Builder
    |--------------------------------------------------------------------------
    |
    | Compass will write and build contents in Documentarian markdown files
    | and as a generator to generate the API documentation which is a
    | PHP port of the popular Slate API documentation tool.
    | Compass将在Documentarian中编写和构建markdown文件并生成API文档
    | @see https://github.com/mpociot/documentarian
    |
    */

    'builder' => 'slate',

    'template' => [
        'slate' => [
            'output' => 'public/docs',
            'example_requests' => [
                'bash',
            ],
        ],
    ],
];

并在public/vendor/compass/生成相应的前端资源。

运行php artisan migrate命令执行迁移，该命令将执行数据库迁移生成compass_routeables表，用于记录测试路由数据

运行php artisan compass:publish命令,该命令将发布compass所需要的前端文件

如果你没有修改配置路由，可通过yourproject.test/compass访问laravel compass界面

可在该界面对相关的API进行测试并保存API的相关信息，在团队开发API时，该扩展包可以更好的上手测试了解相关的API并保存文档。

可运行php artisan compass:build生成相应的API文档，命令执行完成后，可通过yourproject.test/docs/index.html访问文档页面，可对API进行搜索并查看

总结

该扩展包还是十分方便的，对于之前项目中，没有进行API文档编写，也可以通过扩展包进行文档补充说明，在团队开发过程中，让其他人更加容易上手了解API。

本作品采用《CC 协议》，转载必须注明作者和本文链接