README

安装

composer require fillincode/swagger

发布配置

php artisan vendor:publish --provider="Fillincode\Swagger\SwaggerServiceProvider"

配置

OpenApi 版本

'openapi' => '3.0.0',

使用信息配置你的 Api。你可以定义标题、描述、版本、使用条款、联系信息和许可证

'info' => [
    'title' => 'API documentation',
    'description' => 'API documentation',
    'version' => '1.0.0',
    'termsOfService' => 'https://example.com/terms',
    'contact' => [
        'name' => 'example',
        'url' => 'https://example.com',
        'email' => 'example@mail.ru',
    ],
    'license' => [
        'name' => 'CC Attribution-ShareAlike 4.0 (CC BY-SA 4.0)',
        'url' => 'https://openweathermap.org/price',
    ],
],

现成的授权方案

'securitySchemes' => [
    'passport' => [
        'type' => 'http',
        'in' => 'header',
        'name' => 'Authorization',
        'scheme' => 'Bearer',
        'description' => 'To authorize, use the key ',
    ],
    'sanctum' => [
        'type' => 'http',
        'in' => 'header',
        'name' => 'Authorization',
        'scheme' => 'Bearer',
        'description' => 'To authorize, use the key ',
    ],
],

关于请求将发送到的服务器的信息

'servers' => [
    [
        'url' => env('APP_URL'),
        'description' => 'Server for testing',
    ],

服务器授权配置

需要确定是否有需要授权的请求
检查授权的中间件
选择所需的授权方案
你需要定义一个函数或可调用的类，它将返回授权令牌（s）。你可以返回一个包含令牌描述和值的数组，或者只是一个字符串令牌

此类的一个示例

    public function __invoke(): string|array
    {
        $user = User::whereEmail('user@mail.ru')->first();

        return $user?->createToken('user-token')->accessToken;
    }

    ````

    public function __invoke(): string|array
    {
        $user = User::whereEmail('user@mail.ru')->first();
        $admin = User::whereEmail('admin@mail.ru')->first();

        return [
            'user' => $user?->createToken('user-token')->accessToken,
            'admin' => $admin?->createToken('admin-token')->accessToken
        ];
    }

授权配置

'auth' => [
    'has_auth' => true,
    'middleware' => 'auth.api',
    'security_schema' => 'passport',
    'make_token' => [
        'action' => 'makeTokenFunction',
    ],
],

存储测试结果的临时文件的配置。可以确定驱动器和路径

'storage' => [
    'driver' => 'local',
    'path' => 'data',
],

资源键配置

'pre_key' => 'data',

'resources_keys' => [
    'has_pre_key' => false,
    'use_wrap' => true,
],

资源键配置设置的示例

例如，如果有不属于资源的附加键，资源有键，但不是通过 wrap 设置的

响应

'data' => [
    'user' => [
        'id' => 12,
        'name' => 'user_name'
    ]
]

资源

    class UserResource extends JsonResource

    public function toArray(Request $request)
    {
        return [
            'user' => [
                'id' => $this->id,
                'name' => $this->name
            ]           
        ]       
    }

配置

'pre_key' => 'data',

'resources_keys' => [
    'has_pre_key' => true,
    'use_wrap' => false,
],

如果没有附加键在响应中，并且资源使用 wrap 属性作为键

响应

'user' => [
    'id' => 12,
    'name' => 'user_name'
]

资源

    class UserResource extends JsonResource

    public static $wrap = 'user';
    
    public function toArray(Request $request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name        
        ]       
    }

配置

'pre_key' => '',

'resources_keys' => [
    'has_pre_key' => true,
    'use_wrap' => true,
],

如果响应只包含数据，没有任何键

响应

[
    'id' => 12,
    'name' => 'user_name'
]

资源

    class UserResource extends JsonResource
    
    public function toArray(Request $request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name        
        ]       
    }

    public function boot(): void
    {
        JsonResource::withoutWrapping();
    }

配置

'pre_key' => '',

'resources_keys' => [
    'has_pre_key' => false,
    'use_wrap' => false,
],

预定义的响应代码描述。你可以将你自己的响应描述添加到这个数组中

'codes' => [
    200 => 'Request completed successfully',
    201 => 'Object created successfully',
    204 => 'Not content',
    401 => 'Not authentication',
    403 => 'Not authorization',
    404 => 'Not found',
    422 => 'Data validation error',
    500 => 'Server error',
],

命令

清除测试结果目录

php artisan swagger:destroy

从所有测试结果文件生成文档文件

php artisan swagger:parse

运行测试，生成新文档并删除临时文件

php artisan swagger:generate

属性

组

该属性用于对路由进行分组

适用

控制器方法

该参数接受

组名（字符串）。必需

示例

    use Fillincode\Swagger\Attributes\Group;
    
    #[Group('group_name')]
    public function example_method()
    {
        //
    }

摘要

路由的简要描述

适用

控制器方法

该参数接受

摘要（字符串）。必需

示例

    use Fillincode\Swagger\Attributes\Summary;
     
    #[Summary('summary')]
    public function example_method()
    {
        //
    }

描述

路由的详细描述

适用

控制器方法

该参数接受

描述（字符串）。必需

示例

    use Fillincode\Swagger\Attributes\Description;
     
    #[Description('description')]
    public function example_method()
    {
        //
    }

代码

该属性需要用于自定义代码描述

适用

控制器方法

该参数接受

代码（整数）。必需
代码描述（字符串）。必需

示例

    use Fillincode\Swagger\Attributes\Code;
     
    #[Code(201, 'Object update')]
    public function example_method()
    {
        //
    }

PathParameter

该属性需要用于描述通过地址栏传递的参数

适用

控制器方法

该参数接受

参数名称（字符串）。必需
类型（字符串）。必需
描述（字符串）
可用值（字符串|数组）。该参数对于枚举类型是必需的
必需（布尔值）。参数是否必需。默认为 true

示例

    use Fillincode\Swagger\Attributes\PathParameter;
     
    #[PathParameter('parameter_name', 'enum', 'description parameter', ['string_1', 'string_2', 12], false)]
    public function example_method()
    {
        //
    }

QueryParameter

该属性需要用于描述通过 GET 参数传递的参数

适用

控制器方法

该参数接受

参数名称（字符串）。必需
类型（字符串）。必需
示例（字符串/整数/布尔值）。必需
描述（字符串）
可用值（字符串|数组）。该参数对于枚举类型是必需的
必需（布尔值）。参数是否必需。默认为 true

示例

    use Fillincode\Swagger\Attributes\QueryParameter;
     
    #[QueryParameter('parameter_name', 'string', 'example_string', 'description parameter')]
    public function example_method()
    {
        //
    }

资源

该属性用于指示响应中返回的资源。此资源将根据响应数据收集信息。要描述嵌套资源，必须在父资源上定义此属性

适用

控制器方法
资源类

该参数接受

类（字符串）。必需
名称（字符串|null）。此参数仅在资源对象具有键且与资源的 wrap 属性不同时需要
use_wrap（布尔值|null）。如果资源使用 wrap 作为键，则需要传递 true（可以激活配置中的所有资源）
has_key（布尔值|null）。如果资源有键，则需要传递 true（可以配置配置中的所有资源）

示例

    use Fillincode\Swagger\Attributes\Resource;
     
    #[Resource(ProjectResource::class)]
    public function example_method()
    {
        //
    }

    ```` 
    
    #[Resource(CategoryResource::class, 'categories')]
    class ExampleResource extends JsonResource
    {
        //
    }

FormRequest

此属性用于指示通过哪个FormRequest类收集数据来描述请求中传递的参数

适用

控制器方法

该参数接受

类（字符串）。必需

示例

    use Fillincode\Swagger\Attributes\FormRequest;
     
    #[FormRequest(FormRequest::class)]
    public function example_method()
    {
        //
    }

属性

该属性描述了请求中传递的参数或响应中返回的参数

适用

FormRequest类
资源类

该参数接受

名称 (字符串)。必需
类型（字符串）。必需
描述 (字符串)。
输入 (字符串|数组)。可用值，仅对枚举类型需要参数
is_required (布尔值)。默认为true

示例

    use Fillincode\Swagger\Attributes\Property;
     
    #[Property('age', 'integer', 'student age')]
    class ProjectRequest extends FormRequest
    {
        //
    }

    ````
    #[Property('age', 'integer', 'student age')]
    class ProjectResource extends JsonResource
    {
        //
    }

此外

当资源有一个需要文档化键的数组时的一个示例

    use Fillincode\Swagger\Attributes\Property;
    
    #[Property('id', 'string', 'user id')]
    #[Property('data.info_1', 'string', 'user info 1')]
    #[Property('data.info_2', 'string', 'user info 2')]
    class UserResource extends JsonResource
    {
        public function toArray(Request $request)
        {
            return [
                'id' => $this->id,
                'data' => [
                    'info_1' => $this->data['info_1'],
                    'info_2' => $this->data['info_2'],
                ]       
            ]       
        }
    }

fillincode / swagger

维护者

详细信息

README

安装

配置

OpenApi 版本

使用信息配置你的 Api。你可以定义标题、描述、版本、使用条款、联系信息和许可证

现成的授权方案

关于请求将发送到的服务器的信息

服务器授权配置

授权配置

存储测试结果的临时文件的配置。可以确定驱动器和路径

资源键配置

预定义的响应代码描述。你可以将你自己的响应描述添加到这个数组中

命令

属性

组

摘要

描述

代码

PathParameter

QueryParameter

资源

FormRequest

属性

此外