README

基于 DocBlock 注释的 Laravel 5 API 文档生成器。

安装

您可以通过 Composer 安装此包

composer require yaro/apidocs

将此服务提供者和别名添加到 config/app.php

'providers' => [
    //...
    Yaro\ApiDocs\ServiceProvider::class,
    //...
]

'aliases' => [
    //...
    'ApiDocs' => Yaro\ApiDocs\Facade::class,
    //...
]

然后发布配置和资产文件

php artisan vendor:publish --provider="Yaro\ApiDocs\ServiceProvider"

并且您应该在 config/filesystems.php 中添加一个名为 snapshots 的磁盘，blueprint 快照将被保存到该磁盘上

//...
'disks' => [
    //...
    'apidocs' => [
        'driver' => 'local',
        'root'   => storage_path('apidocs'),
    ],
//...    

使用方法

您所有的路由都必须以某个段开始，例如 /api/（已在配置中更改）。该包将仅收集以该段开始的路由。

将您的路由方法 DocBlock 注释添加到其中。例如：

/**
 * Some api endpoint for important stuff.
 * 
 * Just show some template with     
 * some very long description    
 * on several lines
 * 
 * @param int    $offset   Just an offset size
 * @param string $password 
 */
public function getSomeStuff()
{
    return response()->json([]);
}

然后创建一个路由来查看您的文档。

Route::get('/docs', function() {
    return ApiDocs::show();
});

您还可以通过添加 apidocs.auth.basic 中间件强制进行授权提示。授权标识存储在 apidocs.auth.credentials 配置下。

Route::get('/docs', function() {
    return ApiDocs::show();
})->middleware(['apidocs.auth.basic']);

要将某些路由/类排除，请将它们添加到配置的 exclude 中。可以使用星号来表示通配符。

'exclude' => [
    'classes' => [
        // 'App\Http\Controllers\*' - exclude all controllers from docs.
        // 'App\Http\Controllers\MyController@*' - remove all methods for specific controller from docs.
    ],
    
    'routes' => [
        // 'payment/test',
        // 'simulate/*',
    ],
 ],

此外，您还可以创建 API Blueprint 文件

ApiDocs::blueprint()->create();
// or pass snapshot name and/or filesystem disc name
ApiDocs::blueprint()->create('my-newest-snapshot', 's3-blueprint');

或者不创建文件直接渲染其内容

echo ApiDocs::blueprint()->render();

或者通过 artisan

php artisan apidocs:blueprint-create

待办事项

• 生成包含所有文档信息的纯 HTML 页面。
• 包含响应的完整尺寸区块。

许可协议

MIT 许可协议（MIT）。请参阅 LICENSE 获取更多信息。