企业官网建设流程全解析

使用 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 aren't 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 --tag=scribe-config

Laravel 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" } }',

当同时设置多个来源时，优先级为file>content>url。该方案还支持多文档切换（sources配置）、运行时通过ScalarFacade 动态注册文档，以及通过覆写viewScalarGate 来为/scalar路由增加访问鉴权，适合需要版本化文档或内外部文档分离的场景。判断依据很简单：代码是 OpenAPI 的唯一事实来源，选 Scribe；OpenAPI 文件才是唯一事实来源，选 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