使用 Laravel Scribe 生成 OpenAPI 并用 Scalar 渲染 API Reference 的完整接入指南【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本篇技术指南将带你完成一条从零开始的 Laravel API 文档自动化链路使用 Laravel Scribe 从现有代码库自动分析并生成 OpenAPI 文件无需手写任何注解再通过 Scribe 的external_laravel类型将文档交由 Scalar 渲染成现代、可交互的 API Reference。阅读并实践完本文后你将掌握 Scribe 的安装、配置与生成流程理解type与theme两个关键配置项的作用并能在 CI 中持续维护你的 API 文档。Laravel Scribe 与 Scalar 的分工Laravel Scribe 是一个优秀的开源包它能从你已有的 Laravel 代码库中直接分析并生成 OpenAPI 文件。正如其文档所说Clumsy annotations arent required, the package will just analyze your code——繁琐的手写注解不是必需的Scribe 会直接分析你的控制器、路由和模型因此你不需要额外维护一份与代码脱节的 API 定义。需要注意的是本指南的链路是Scribe 负责生成、Scalar 负责渲染Laravel Scribe负责从代码生成 OpenAPI 文档并将/docs路由指向 Scalar 渲染器Scalar负责把 OpenAPI 文档渲染成漂亮的 API Reference 页面。如果你不需要从代码生成 OpenAPI而只是想把已有的 OpenAPI 文档渲染成文档页面仓库中还提供了另一条更直接的路径——Scalar for Laravel它不自带 OpenAPI 生成能力而是直接渲染现有的 OpenAPI 文档安装方式为composer require scalar/laravel后执行php artisan scalar:install。本文末尾会给出这条替代方案的要点两条路线可以根据项目阶段灵活选择。创建 Laravel 项目可选如果你是从零开始先通过 Composer 安装 Laravel 安装器composer global require laravel/installer~1.1安装完成后一条命令即可创建一个新的 Laravel 应用laravel new my-new-app本指南使用的交互式预设如下其他预设同样可以正常工作这里的选择只是为了方便复现┌ Would you like to install a starter kit? ────────────────────┐ │ Laravel Breeze │ └──────────────────────────────────────────────────────────────┘ ┌ Which Breeze stack would you like to install? ───────────────┐ │ Blade with Alpine │ └──────────────────────────────────────────────────────────────┘ ┌ Would you like dark mode support? ───────────────────────────┐ │ Yes │ └──────────────────────────────────────────────────────────────┘ ┌ Which testing framework do you prefer? ──────────────────────┐ │ Pest │ └──────────────────────────────────────────────────────────────┘ ┌ Would you like to initialize a Git repository? ──────────────┐ │ Yes │ └──────────────────────────────────────────────────────────────┘初始化过程大约需要一分钟。完成后进入新项目目录cd my-new-app本示例选择了 SQLite 作为数据库驱动因此需要先创建一个空的数据库文件touch database/database.sqlite如果你选择了其他数据库驱动请把对应的凭据补充到项目的.env文件中。一切就绪后可以使用 Laravel Herd或者直接在命令行启动一个轻量的 PHP 内置服务器php artisan serve现在打开 http://127.0.0.1:8000你应该能看到 Laravel 的默认起始页了。安装并配置 Laravel Scribe项目跑起来之后就可以安装 Laravel Scribe 了它会为你的 API 生成机器可读的 OpenAPI 描述文件composer require --dev --with-all-dependencies knuckleswtf/scribe随后把 Scribe 的默认配置发布到项目目录中php artisan vendor:publish --tagscribe-configLaravel Scribe 自带大量配置项但本指南只需要切换到 Scalar 作为 API Reference 渲染器。请在发布出来的 Scribe 配置文件中修改以下两个值- type static, type external_laravel, - theme default, theme scalar,这两个配置项的含义需要重点理解type决定 Scribe 生成文档的呈现方式。默认的static会生成一套静态 HTML 页面external_laravel则把渲染工作交给外部的 Scalar 渲染器由 Scribe 负责在/docs路由上提供文档数据theme决定渲染时使用的主题。scalar即使用 Scalar 主题风格。若未来你想在 Scribe 之外的场景直接使用 Scalar 的 API Reference可选的theme取值以仓库中的 配置文档 为准包括alternate、default、moon、purple、solarized、bluePlanet、saturn、kepler、mars、deepSpace、laserwave以及表示不应用任何主题的none默认值为default。更多主题细节可参考 Themes 文档。配置完成现在可以生成你的第一个 OpenAPI 文件了php artisan scribe:generate如果好奇生成结果可以打开storage/app/scribe/openapi.yaml查看。这份 YAML 文件应该已经描述了你的 API——对于刚创建的全新 Laravel 项目来说它通常只包含一个路由/api/user。查看你的 API Reference生成完成后来看看成果。重新启动 PHP 服务器php artisan serve然后在浏览器中打开http://127.0.0.1:8000/docs你会看到由 Scalar 渲染的 API Reference 页面。至此Laravel Scribe 的基本接入就完成了。源码佐证Scalar 对 Laravel 生态的原生支持在本次接入中你看到的并不仅仅是一个通用的文档页面。从仓库源码可以看到Scalar 的代码示例生成体系针对 Laravel 做了专门适配在 packages/snippetz/src/plugins/php/laravel/laravel.ts 中定义了一个target: php、client: laravel的代码片段插件能够基于请求信息直接生成 Laravel HTTP Client 风格的示例代码自动引入use Illuminate\Support\Facades\Http;根据请求方法选择Http::get(...)/Http::post(...)等直接调用或Http::send(...)通用发送根据请求内容自动拼接withHeaders(...)、withCookies(...)、asForm()、attach(...)等链式方法支持 Basic Auth 的withBasicAuth(...)以及 JSON、application/x-www-form-urlencoded、multipart/form-data、application/octet-stream等多种请求体的正确处理。这意味着你的 API Reference 中可以直接为使用者展示 Laravel 开发者熟悉的请求示例而不是只有 curl 一种选择。这是选择 Scalar 渲染 Scribe 文档时一个容易被忽略、但实际体验差异明显的细节。让文档保持最新自动化生成每次你更新 API 之后都需要重新运行php artisan scribe:generate来更新 OpenAPI 文件以及对应的 API Reference。如果觉得手动执行比较繁琐可以把vite-plugin-watch加入你的 Vite 配置来监听文件变更并自动触发重新生成。此外把以下命令加入你的 CI 流程也是值得的php artisan scribe:generate这样每次部署/构建时都会自动同步最新的 API 文档避免文档与代码漂移。进阶替代方案已有 OpenAPI 文档时直接用 Scalar for Laravel如果你已经拥有一份 OpenAPI 文档例如由 dedoc/scramble、knuckleswtf/scribe 或 vyuldashev/laravel-openapi 等包生成可以直接使用 Scalar for Laravel 跳过生成环节仅负责渲染。其核心配置在config/scalar.php中支持三种文档来源// 方式一URL——由浏览器请求获取同源相对路径或公开的绝对地址 url /openapi.yaml, // url https://example.com/openapi.json, // 方式二本地文件——在服务端读取并内嵌进页面无需公开访问 file storage_path(app/openapi.json), // 方式三内联内容——直接以 JSON 或 YAML 字符串提供 content { openapi: 3.1.0, info: { title: My API, version: 1.0.0 } },当同时设置多个来源时优先级为filecontenturl。该方案还支持多文档切换sources配置、运行时通过ScalarFacade 动态注册文档以及通过覆写viewScalarGate 来为/scalar路由增加访问鉴权适合需要版本化文档或内外部文档分离的场景。判断依据很简单代码是 OpenAPI 的唯一事实来源选 ScribeOpenAPI 文件才是唯一事实来源选 Scalar for Laravel。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考