README

免责声明

此包是 HCESrl/laravel-swagger-api 的分支，添加了一些更新，例如

支持 Laravel 9
支持 PHP 7.4
支持使用模式响应

包

该包在 Laravel 路由系统之上增加了一层，允许您轻松地为路由添加元数据，以创建符合 Swagger UI 规范的 API。

安装

安装包

composer require hcesrl/laravel-swagger-api

发布配置和资源

php artisan vendor:publish --provider="LaravelApi\ServiceProvider"

基本用法

配置

主要配置位于 config/api.php 文件中。在这里，您可以设置一些 API 规范的一般元数据，例如标题、描述等。

确保 prefix 与您的 RouteServiceProvider 中用于 API 路由的相同。

HTTPS/受信任的代理

如果您的 API 在负载均衡器后面托管且不生成正确的安全 URL，请参阅 Laravel 文档中有关配置受信任的代理的说明。

路由

Api 门面与 Route 门面使用相同的语法，并且您可以直接在 routes/api.php 文件中使用它。

use LaravelApi\Facade as Api;

Api::get('some-uri', 'Controller@action');

Api::post('some-uri', function () {
    // do something
});

注意：支持的方法： get、post、put、delete、patch、options。由于每个路由都必须与 Swagger 规范中的单个操作关联，因此不支持 match 方法。

当您创建一个新的路由时，Api 门面返回一个 Operation 对象的实例。该对象公开了一些可链式配置方法。以下示例展示了这些方法的广泛使用。

use LaravelApi\Facade as Api;

Api::get('some-uri', 'Controller@action')
    ->setSummary('My operation summary')
    ->setDescription('My operation description')
    ->addTag('some-tag')
    ->setOperationId('executeAction')
    ->setConsumes(['application/json'])
    ->setProduces(['application/json']);

路由参数

您可以通过以下方法在创建路由后定义不同类型的路由参数

addHeaderParameter
addQueryParameter
addPathParameter
addFormDataParameter
addBodyParameter

所有这些方法都接受 4 个参数：名称、描述、必需性和类型

use LaravelApi\Facade as Api;

Api::post('post-uri', 'Controller@action')
    ->addHeaderParameter('header-name', 'Some description.')
    ->addQueryParameter('query-name', 'Some description.', true, 'integer')
    ->addPathParameter('path-name', 'Some description.', true, 'string')
    ->addFormDataParameter('formdata-name', 'Some description.', true, 'string')
    ->addBodyParameter('param-name', 'Some description.', true);

注意：addBodyParameter 方法不接受 type 参数，根据 Swagger 规范。

如果您需要更详细的参数配置，您可以传递一个闭包函数而不是文本描述

use LaravelApi\Facade as Api;

Api::post('post-uri-2', 'Controller@action')
    ->addQueryParameter('param-name', function($param) {
        $param->setDescription('Some param description')
              ->setType('integer')
              ->setFormat('int32');
    });

路由路径参数自动解析

当您使用 Laravel 语法定义包含路径参数的路由时，路由 URI 将自动解析路径参数，包括必需的和可选的。

路由

use LaravelApi\Facade as Api;

Api::get('some-uri/{param1}/{param2?}', 'Controller@action');

将被解析，并将两个路径参数自动添加。您仍然可以编辑参数配置

use LaravelApi\Facade as Api;

Api::get('some-uri/{param1}/{param2?}', 'Controller@action')
   ->addPathParameter('param1', function( $param) {
       $param->setDescription('Some description');
   })
   ->addPathParameter('param2', 'Some other description.', false, 'integer');

您还可以通过在主配置文件 config/api.php 中设置 parse_route_parameters 为 false 来禁用自动路由解析。

响应

使用 addResponse 来定义路由响应类型

use LaravelApi\Facade as Api;

$pet = Schema::create()
    ->addRequired('id')
    ->addRequired('name')

    ->setProperties(Properties::create()
        ->set('id', Schema::create()
            ->setType('integer')
            ->setFormat('int64')
        )
        ->set('name', Schema::create()
            ->setType('string')
        )
        ->set('tag', Schema::create()
            ->setType('string')
        )
    );
    
$error = Schema::create()
    ->addRequired('code')
    ->addRequired('message')

    ->setProperties(Properties::create()
        ->set('code', Schema::create()
            ->setType('integer')
            ->setFormat('int32')
        )
        ->set('error', Schema::create()
            ->setType('string')
        )
    );

Api::get('some-uri', 'Controller@action')
   ->addResponse(200, 'Successful operation', $pet)
   ->addResponse(422, 'Validation error', $error);

高级配置

通用路由参数

您可能需要使用相同的参数（例如 lang 或 locale）注册不同的路由，这可能导致路由文件变得很长且难以维护。

为了避免这种情况，您可以注册通用的可重用路由参数，当在路由 URI 中找到具有相同参数时，这些参数将自动应用。

use LaravelApi\Facade as Api;

Api::routeParameter('locale')
   ->setDescription('The request locale.')
   ->setRequired(true)
   ->addOptions('en', 'it');
   
Api::get('{locale}/some-uri', 'Controller@action');

从 FormRequest 猜测参数

为了简化参数注册，您可以将 Laravel 的 FormRequest 直接绑定到一个路由上，并让包从请求规则中猜测参数。

use LaravelApi\Facade as Api;

Api::post('some-uri', 'Controller@action')
   ->bindRequest('App\\Http\\Requests\\MyFormRequest');

版本

如果您想根据不同的版本对路由进行分组，可以使用 version 方法。分组后的路由将自动使用给定的版本名称进行前缀和标签。

use LaravelApi\Facade as Api;

/**
 * /api/v1/versioned-uri
 */
Api::version('v1', function () {
    Api::get('versioned-uri', 'Controller@action');
});

/**
 * /api/v2/versioned-uri
 */
Api::version('v2', function () {
    Api::get('versioned-uri', 'Controller@action');
});

聚合资源端点

聚合端点是返回资源混合集合的 API 端点，这些资源结合了 Eloquent 模型和闭包生成的数据。

use LaravelApi\Facade as Api;

Api::aggregate('aggregate/uri', [
    'App\\Page',
    'App\\Post',
    'settings' => function(SettingStore $settings) {
        return $settings->all();
    },
]);

注意：闭包需要非数字数组键。

聚合模型端点

构建复杂的 API 可能需要创建多个暴露模型数据的端点。您可以使用 models 快捷方式轻松地做到这一点。使用此方法，您可以创建一个通用的资源端点，该端点连接到仅实现 index 和 show 操作的简单资源控制器，并处理多个模型。

以下配置

use LaravelApi\Facade as Api;

Api::models([
    'pages' => \App\Page::class, 
    'users' => \App\User::class
]);

等同于

use LaravelApi\Facade as Api;

Api::resource('models/pages', 'SomeController')
   ->only('index', 'show');
    
Api::resource('models/users', 'SomeController')
   ->only('index', 'show');

自定义响应

如果您使用自定义 API 资源来个性化 API 数据，您可以在模型中定义以下方法，以便为 API 服务器提供正确的资源。

class Foo extends Model 
{

    public function toApiResource($resource)
    {
        return new MyCustomResource($resource);
    }
    
    
    public function toApiResourceCollection($resource)
    {
        return new MyCustomResourceCollection($resource);
    }

}

授权

为了为规范提供安全定义，您可以使用以下方法之一

use LaravelApi\Facade as Api;

Api::basicAuthSecurity('basic_auth');

Api::apiKeySecurity('api_key')
   ->parameterName('apiKey')
   ->inHeader();

Api::oauth2ImplicitSecurity('oauth2_implicit')
   ->authorizationUrl('http://www.foobar.com')
   ->description('A description for the auth.')
   ->setScopes([
       'write' => 'Write something',
       'read'  => 'Read something',
  ]);

Api::oauth2PasswordSecurity('oauth2_password')
   ->tokenUrl('http://www.foobar.com')
   ->setScopes(...);

Api::oauth2ApplicationSecurity('oauth2_application')
   ->tokenUrl('http://www.foobar.com')
   ->setScopes(...);

Api::oauth2AccessCodeSecurity('oauth2_accesscode')
   ->tokenUrl('http://www.foobar.com')
   ->setScopes(...);

在任意操作中，您可以通过 requiresAuth 方法设置所需的认证方案

Api::get('some-uri', 'Controller@action')
   ->requiresAuth('oauth2_implicit', ['read']);

以及在资源中

Api::resource('models/pages', 'SomeController')
   ->requiresAuth('oauth2_implicit', ['read']);

API Json 缓存

要生成 Swagger UI JSON 文件缓存，只需执行 api:cache Artisan 命令

php artisan api:cache

运行此命令后，您的缓存 JSON 文件将被使用。请记住，如果您向 API 添加任何新路由，您将需要生成一个新的路由缓存。因此，您应在项目的部署期间运行 api:cache 命令。

您可以使用 api:clear 命令清除 API 缓存

php artisan api:clear

待办事项

添加对安全定义的支持；
添加对组件的支持；
添加对响应示例的支持；
通过 Laravel Passport 实现认证；

许可

此软件包是开源软件，根据 MIT 许可证授予许可。

zabaala / laravel-swagger-api

维护者

详细信息