Scribe: 轻松生成 Laravel API 文档

Scribe: 轻松生成 Laravel API 文档

Scribe 是一个强大的工具，可以帮助节省大量手动编写文档的时间。通过遵循本指南，您可以在 Laravel 项目中轻松设置 Scribe，根据需求进行配置，并生成美观、最新的 API 文档，而只需付出最少的努力。

简介

API进行文档记录对于开发人员理解如何有效地与之交互变得愈发重要。

编写技术文档对于许多程序员来说是一个挑战，这主要是因为两个普遍存在的问题：一是缺乏编写文档的动力，二是文档编写标准的不一致性。

Laravel 是最流行的 PHP 框架之一，它提供了一个名为 Scribe 的强大工具，用于生成全面的 API 文档。

Scribe 是由 Knuckles.wtf 团队开发的开源包。它利用 Laravel 强大的路由和中间件系统，为您的 API 生成美观且可交互的文档。在这篇博文中，我们将探讨如何在您的 Laravel 项目中设置 Scribe，根据您的需求进行配置，以及生成让您的工作更轻松的文档。

与 Laravel 的 Scribe 类似的，其他框架如 Symfony 拥有 ApiPlatform，而 CodeIgniter 提供了 API 工具集，它们都旨在简化 API 文档的创建和维护。然而，Scribe 以其简洁的配置和易用性在 Laravel 生态系统中独树一帜。通过 Scribe，开发者可以快速生成清晰、结构化的文档，从而提高团队协作的效率和API的可用性。这不仅减少了开发时间，也降低了因文档不明确而产生的误解和错误。

Introduction | Scribe这里进入官方文档

在 Laravel 项目中设置 Scribe

在深入了解配置细节之前，让我们先在Laravel 项目中安装 Scribe。打开终端，导航到项目根目录，然后运行以下命令：

composer require --dev knuckleswtf/scribe

此命令将把 Scribe 作为开发依赖项安装到项目中。安装完成后，您需要通过运行以下命令发布 Scribe 的配置文件：

php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider"

此命令将在您的项目目录的 config 目录中创建一个名为 scribe.php 的新文件。现在您可以根据需要自定义配置。

配置 Scribe

Scribe 提供了各种配置选项，可以根据特定需求定制生成的文档。

让我们看一些基本的配置选项：

<?php

return [
    // 文档标题
    'title' => '我的 API 文档',

    // 对您的 API 的简短描述
    'description' => '这是我令人惊叹的 API 的文档。',

    // API 的基本 URL
    'base_url' => env('APP_URL'),

    // 要包含在文档中的路由
    'routes' => [
        [
            'match' => [
                'prefixes' => ['api/*'],
                'domains' => ['*'],
            ],
            'exclude' => [
                'api/documentation',
            ],
        ],
    ],

    // ...
];

在这个例子中，我们设置了文档的标题、描述和基本 URL。我们还配置了 Scribe 以包含所有以 api/* 为前缀的路由，并排除 api/documentation 路由。

您可以在 config/scribe.php 文件中找到更多配置选项，例如身份验证设置、示例语言以及用于生成 Postman 集合和 OpenAPI 规范的选项。

生成文档

配置好 Scribe 后，您可以通过运行以下命令生成文档：

php artisan scribe:generate

此命令将分析您的应用程序的路由、控制器和请求/响应转换器，以生成全面的 API 文档。根据您项目的规模和复杂性，此过程可能需要一些时间才能完成。

如果将 Scribe 配置为生成静态 HTML 页面 (type' => 'static'), 生成的文档将默认保存到 public/docs 目录中。然后，您可以通过在您的网络浏览器中访问 http://your-app-url/docs 来访问文档。

或者，如果您将 Scribe 配置为生成 Blade 视图 (type' => 'laravel'), 文档可以通过 Scribe 定义的路由进行访问。默认情况下，此路由是 /docs，但您可以在配置文件中进行更改。

当然也可以根据自己的需求来修改生成的模版

TPS

• Scribe 工具主要通过解析 DocBlock 注释和特定的注解来创建文档。为了确保文档的准确性和完整性，请为您的路由定义、控制器逻辑以及请求和响应的处理类添加恰当的 DocBlock 注释和注解。

  创建响应样例：Scribe 具备根据您应用程序中定义的数据模型和转换逻辑自动生成 API 接口的示例输出的能力。

  文档更新：对 API 进行修改后，重要的是要重新执行 php artisan scribe:generate 命令以更新生成的文档，确保文档与当前 API 状态保持一致。