README

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

安装

hc
安装包

composer require hcesrl/laravel-swagger-api

发布配置和资源

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

基本用法

配置

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

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

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;

Api::get ( 'some-uri', 'Controller@action' )
   ->addResponse ( 200, 'Successful operation' )
   ->addResponse ( 422, 'Validation 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 Resources 来个性化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

待办事项

添加对securityDefinitions的支持；
添加对Components的支持；
添加对响应Examples的支持；
通过Laravel Passport实现身份验证；

许可

此包是开源软件，许可协议为MIT许可。

hcesrl / laravel-swagger-api

维护者

详细信息