Larel如何为API编写文档_Larel API文档生成与维护方法

技术教程
2025-12-14 15:33:07

使用Scribe可自动化生成Lar*el项目API文档，通过注释和配置生成交互式页面；2. 结合Lar*el Sanctum可在文档中集成Bearer Token认证说明；3. 将scribe:generate命令纳入CI/CD流程，确保文档与代码同步更新；4. 支持导出静态HTML，便于部署到Web服务器或GitHub Pages；5. 替代方案如L5-Swagger支持OpenAPI标准，适合需对接外部系统的场景。

laravel如何为api编写文档_laravel api文档生成与维护方法

为Lar*el项目编写和维护API文档，是确保前后端协作顺畅、提升开发效率的重要环节。单纯依靠手动书写Markdown或使用Postman导出快照难以长期维护。幸运的是，Lar*el社区提供了多种高效工具来自动化生成和更新API文档。以下是主流且实用的方法。

使用Scribe自动生成API文档

Scribe 是目前Lar*el生态中最受欢迎的API文档生成工具。它通过分析你的路由、控制器、请求类和注释，自动生成美观、交互式的文档页面。

安装与配置：

通过Composer安装： composer require --dev knuckleswtf/scribe
发布配置文件： php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config
配置 config/scribe.php 文件，设置文档标题、描述、基础URL等信息

编写注释以生成文档：

在控制器方法上方添加特定格式的注释，例如：

/**
 * @apiResourceApp\Models\User
 * @apiResourceModel App\Models\User
 * 获取用户列表
 *
 * 返回所有用户的分页数据。
 * 
 * @queryParam page int 可选。当前页码。Example: 1
 * @queryParam search string 可选。搜索关键词。Example: john
 * @response 200 {
 *   "data": [
 *     {"id": 1, "name": "John Doe", "email": "john@example.com"}
 *   ],
 *   "meta": {"current_page": 1}
 * }
 */
public function index(Request $request)
{
    return User::paginate();
}

运行命令生成文档：php artisan scribe:generate，文档将输出到 public/docs 目录，可通过浏览器访问。

结合Lar*el Sanctum进行认证文档说明

如果你的API使用了 Lar*el Sanctum 进行身份验证，可以在Scribe中配置认证方式，让文档自动包含鉴权说明。

在 config/scribe.php 中设置：

Get笔记

Get笔记，一款AI驱动的知识管理产品

774 查看详情 Get笔记

'auth' => [
    'enabled' => true,
    'in' => 'bearer', // 放在Authorization头
    'name' => 'token', // 实际上Sanctum用的是Bearer token
    'use_value' => env('SANCTUM_TOKEN_FOR_DOCS', ''),
],

这样生成的接口文档会提示用户需要提供有效的Bearer Token，并可在测试界面中填写Token进行调试。