README

API 版本化器 是一个用于管理 Laravel 应用程序 API 版本的通用包。它支持灵活的路由、自动版本化和弃用通知，确保 API 版本之间的平稳过渡，同时保持向后兼容性。

安装

您可以通过 Composer 安装此包

composer require ahmedessam/api-versionizer

使用方法

步骤 1：发布配置文件

在开始使用 API 版本化器包之前，您必须使用 Laravel 内置命令发布配置文件

php artisan vendor:publish --tag=apiversionizer-config

这将在您的 config 目录中创建一个名为 api-versionizer.php 的配置文件。配置文件包含以下选项

current_version：API 的当前版本。
fallback_version：如果找不到请求的版本，将使用的回退版本。
strategy：要使用的版本化策略（例如，uri、header、query）。
versioning_key：用于版本化的键（例如，v、version）。
prefix：用于版本化路由的前缀。
default_version：未指定版本时使用的默认版本。
default_directory：用于版本化文件的默认目录。
versioned_folders：包含版本化文件的目录数组。
middlewares：应用于版本化路由的中间件类数组。
default_files：用于版本化路由的默认文件数组。
versions：支持的 API 版本数组。

步骤 2：配置 API 版本

配置文件发布后，您可以通过编辑 api-versionizer.php 文件来配置 API 版本。您可以指定当前版本、回退版本、版本化策略、版本化键、前缀、默认版本、默认目录、版本化文件夹、中间件、默认文件和支持的版本。

以下是 API 版本化的示例配置

'versions' => [
    'v1' => [
        'name'        => 'v1',
        'description' => 'First version of the API',
        'status'      => 'active',
        'files' => [
            [
                'name'        => 'users',
                'as'          => 'users',
                'prefix'      => 'users',
                'namespace'   => 'Users',
                'middlewares' => ['auth:api'],
            ],
        ],
    ],
    'v2' => [
        'name'        => 'v2',
        'description' => 'Second version of the API',
        'status'      => 'active',
        'files' => [
            [
                'name'        => 'users',
                'as'          => 'users',
                'prefix'      => 'users',
                'namespace'   => 'Users',
                'middlewares' => ['auth:api'],
            ],
            [
                'name'        => 'posts',
                'as'          => 'posts',
                'prefix'      => 'posts',
                'namespace'   => 'Posts',
                'middlewares' => ['auth:api'],
            ],
        ],
    ],
],

在此示例中，我们定义了一个带有描述和状态的版本 v1。我们还指定了版本化文件及其名称、别名、前缀、命名空间和中间件。

注意：您可以根据需要添加任意多个版本和文件以支持您的 API 版本化需求，版本数组中的状态可以是 active（活动）、inactive（非活动）或 deprecated（已弃用）来表示版本的当前状态。

步骤 3：运行版本化器命令

配置 API 版本后，您可以通过运行版本化器命令来自动生成版本化路由和文件

php artisan api:versionize --versions=v1,v2

该命令将根据 api-versionizer.php 文件中指定的配置创建版本化路由和文件。它将为每个版本化文件生成带有适当版本前缀和中间件的路线。

步骤 4：访问版本化路由

生成版本化路由后，您可以使用 URL 中的版本前缀来访问它们。例如，要访问版本 v1 中的 users 路由，您可以使用以下 URL

http://example.com/api/v1/users/users

此 URL 包含在配置文件中指定的版本前缀 v1 和路由前缀 users。

处理弃用通知

如果您需要弃用API的一个版本，您可以在配置文件中将版本状态更新为已弃用，并将deprecated_at设置为版本将弃用的日期。Versionizer包将自动处理弃用通知，并在访问已弃用的版本时返回错误。

复制版本到新版本

如果您需要将一个版本复制到新版本，可以运行以下命令

php artisan api:versionize --copy=v1 --to=v2

此命令将版本v1复制到版本v2，并将基于现有版本生成新版本的路由和文件，命名空间也将更新为新版本。

删除版本

如果您需要删除一个版本，可以运行以下命令

php artisan api:versionize --delete=v1

此命令将删除版本v1，并将删除指定版本的版本化路由和文件。

功能

灵活的路由：使用自定义前缀、命名空间和中件定义版本化路由。
自动版本化：根据配置自动生成版本化路由和文件。
弃用通知：处理API版本的弃用通知，并在访问已弃用的版本时返回错误。
版本复制：将现有版本复制到新版本，并为新版本生成版本化路由和文件。
版本删除：删除现有版本，并移除指定版本的版本化路由和文件。

要求

PHP 8.2或更高版本
Laravel 10.0或更高版本
Composer

许可证

API Versionizer包是开源软件，根据MIT许可证授权。

作者

艾哈迈德·艾萨姆

贡献

欢迎贡献！请随时提交Pull Request。

问题

如果您发现此包有任何问题或有任何疑问，请随时在GitHub仓库中打开一个问题。

在您的Laravel应用程序中使用API Versionizer包愉快！🚀

ahmedessam / api-versionizer

维护者

详细信息