README

此包是 Laravel 框架的一个花哨的封装。您必须了解 waffler/waffler 和 guzzlehttp/guzzle 包的基本知识。

安装

composer require waffler/waffler-laravel

php artisan waffler:install # publish the config file

如何配置

此包公开一个 waffler.php 配置文件，以将您的客户端接口注册到应用程序的 服务容器 中。

clients 数组

在服务容器中注册您的客户端。

'clients' => [
    App\Clients\MyClientInterface::class => [/* GuzzleHttp options */],
],

aliases 数组

为您的客户端指定别名。

'aliases' => [
    App\Clients\MyClientInterface::class => 'my-custom-alias',
],

global_options 数组

一个用于所有客户端实例的 guzzle http 选项数组。

'global_options' => [/* GuzzleHttp options */],

singletons 数组

要注册为单例的客户端数组。

'singletons' => [
    App\Clients\MyClientInterface::class,
],

auto_generated_clients 数组

自动生成类的数组。不要修改它，此数组的内容将在您运行 waffler:generate-code 命令时自动生成。

'auto_generated_clients' => [
    'App\Clients\FooBarClientInterface',
],

code_generation 选项

如果您有一个 swagger 或其他 open-api 规范文件，此包还可以生成客户端接口。

'code_generation' => [
    'namespace' => 'App\\Clients',
    'openapi_files' => []
]

code_generation.namespace 选项

所有接口都将生成的基命名空间。

此命名空间将自动转换为相对于 app/ 文件夹的路径。

'namespace' => 'App\\Clients',

code_generation.openapi_files 数组

生成代码的 openapi 文件路径。您可以指定仅 openapi 文件路径，或提供一个生成选项数组。请参阅下面的示例 1 和示例 2。

'openapi_files' => [
    // Example 1:
    resource_path('swagger/my-swagger-file.json'),
    
    // Example 2 with custom options:
    resource_path('swagger/my-swagger-file.json') => [
        'namespace' => 'MyCustomApi',
        'namespace_options' => [
            'base_uri' => env('MY_CUSTOM_API_BASE_URI')
        ],
        'ignore' => [
            'parameters' => [
                'header' => ['X-SOME-HEADER-NAME']
            ]
        ]
    ]
],

code_generation.openapi_files.*.namespace 选项

生成的客户端将放入 code_generation.namespace 加上此选项值。

'namespace' => 'App\\Clients',
'openapi_files' => [
    resource_path('swagger/my-swagger-file.json') => [
        'namespace' => 'MyCustomApi', // Will be converted to App\Clients\MyCustomApi
    ],
],

code_generation.openapi_files.*.spec_type 选项

指示规范文件的模式类型。它可以是 openapi 或 swagger。默认值为 openapi

'namespace' => 'App\\Clients',
'openapi_files' => [
    resource_path('swagger/my-swagger-file.json') => [
        'namespace' => 'MyCustomApi',
        'spec_type' => 'swagger',
    ],
],

code_generation.openapi_files.*.namespace_options 选项

配置命名空间下生成的客户端将共享此 guzzle 配置。这很有用，例如，当客户端共享相同的选项时，如 base_uri。

'openapi_files' => [
    resource_path('swagger/my-swagger-file.json') => [
        'namespace' => 'MyCustomApi',
        'namespace_options' => [
            'base_uri' => env('MY_CUSTOM_API_BASE_URI')
        ],
    ],
],

code_generation.openapi_files.*.ignore 选项

此选项仍在开发中，但您可以在此忽略一些方法参数的生成。将来，这将允许更多的配置。

在下面的示例中，一个名为 HeaderParam 的 Authorization 不会包含在生成的参数中。

'openapi_files' => [
    resource_path('swagger/my-swagger-file.json') => [
        'ignore' => [
            'parameters' => [
                'header' => ['Authorization']
            ]
        ],
        'namespace_options' => [
            'headers' => [
                'Authorization' => env('MY_CLIENT_API_KEY')
            ],
        ],
    ],
],

示例代码

忽略前

<?php

use Waffler\Attributes\Request\HeaderParam;

interface MyClientInterface
{
    public function users(#[HeaderParam('Authorization')] string $authorization): array;
}

忽略后

<?php

use Waffler\Attributes\Request\HeaderParam;

interface MyClientInterface
{
    public function users(): array;
}

可忽略的参数类型包括

• header
• path
• query
• body
• formData

code_generation.openapi_files.*.auto_bind 选项

自动在服务容器中注册生成的接口。默认值为 true。

'openapi_files' => [
    resource_path('swagger/my-swagger-file.json') => [
        'auto_bind' => false
    ],
],

贡献

进行中。