README

Laravel Swagger 会扫描您的 Laravel 项目的端点并自动为您生成 Swagger 2.0 文档。

关于

Laravel Swagger 根据 Laravel 推荐的最佳实践工作。它将解析您的路由并为每个路由生成一个路径对象。如果您在控制器操作中注入表单请求类作为请求验证，它也会为具有它们的每个请求生成参数。对于参数，它会考虑请求是 GET/HEAD/DELETE 还是 POST/PUT/PATCH 请求，并尽可能猜测应生成的参数对象类型。如果您的路由包含路径参数，它也会生成路径参数。最后，此包还会扫描您的操作方法中的任何文档，并将其作为摘要和描述添加到该路径中，以及任何适当的注释，如 @deprecated。

需要注意的是，这个库倾向于明确性。即使它们有默认值，它也会选择包含键。例如，它选择说明路由有一个废弃的值为 false，而不是省略它。如果用户选择省略默认值，文件可以很容易地进行清理。

安装

您可以通过在项目根目录中运行 composer require laxity7/laravel-swagger 来轻松安装此包。

这将注册可供您使用的 artisan 命令。

您还可以通过在项目根目录中运行 php artisan vendor:publish --provider "Laxity7\LaravelSwagger\SwaggerServiceProvider" 来覆盖应用程序提供的默认配置，并在新创建的 config/laravel-swagger.php 文件中更改配置。

使用方法

像平时一样编写代码，使用 Laravel 推荐的最佳实践。此包将扫描您的路由和控制器，并为您生成文档。生成 Swagger 文档很简单，只需在项目根目录中运行 php artisan laravel-swagger:generate 即可。

请注意，该命令将简单地将其输出打印到您的控制台。如果您想将其保存到文件中，可以像这样重定向输出：php artisan laravel-swagger:generate -o swagger.json

如果您只想为路由子集生成文档，可以使用 --filter 传递过滤器，例如：php artisan laravel-swagger:generate --filter="/api"

默认情况下，laravel-swagger 以 json 格式打印文档。如果您想以 YAML 格式，可以使用 --format (-f) 标志覆盖格式。如果您选择这样做，请确保已安装 yaml 扩展或 symfony/yaml 包。默认格式选项为：json 或 yaml。您可以通过添加一个实现 Laxity7\LaravelSwagger\Generators\FormatGenerator 接口的新类并将它添加到 config/laravel-swagger.php 文件中的 'formats' 数组中来添加自己的格式。

默认情况下，将文档打印到控制台。如果您想将其保存到文件中，可以使用 --output (-o) 标志覆盖输出。

代码中的使用

您还可以通过使用 Laxity7\LaravelSwagger\Generator 类在您的代码中使用此包。

use Laxity7\LaravelSwagger\Generator;

$generator = new Generator();
$generator->generate();

自定义

自定义请求生成器

您可以通过添加一个实现 Laxity7\LaravelSwagger\Parsers\Requests\Generators\ParameterParser 接口的新类并将其添加到 config/laravel-swagger.php 文件中的 'parameterParsers' 数组中来向该包添加自己的自定义请求生成器。

例如，假设您有一个名为 App\Swagger\CustomBodyParameterGenerator 的自定义请求生成器类。您可以像这样将其添加到 'parameterParsers' 数组中

'parameterParsers' => [
    \Laxity7\LaravelSwagger\Parsers\Requests\Parameters\PathParameterParser::class,
    \Laxity7\LaravelSwagger\Parsers\Requests\Parameters\QueryParameterParser::class,
    \App\Swagger\CustomBodyParameterGenerator::class,
],

示例

您的路由文件可能如下所示

Route::get('/api/user/{id}', ['UserController', 'show']);
Route::get(
    '/api/user/{id}/check',
    /** 
    * Check user exist
    * @param int $id User ID 
    */ 
    fn(int $id) => User::where('id', $id)->exists();
);

您的示例控制器可能如下所示

use Laxity7\LaravelSwagger\Attributes\Request;

class UserController extends Controller
{
    /**
    *  Return all the details of a user
    *
    * Returns the user's first name, last name and address
    * Please see the documentation [here](https://example.com/users) for more information
    *
    * @deprecated
    * 
    * @param int $id User ID
    */
    public function show(UserShowRequest $request, int $id)
    {
        return User::find($id);
    }
    
    /**
    * @request UserShowRequest
    */
    public function show(int $id)
    {
        $showRelationships = request()->get('show_relationships')
        return User::find($id);
    }

    #[Request(UserShowRequest::class)]
    public function show(int $id)
    {
        $showRelationships = request()->get('show_relationships')
        return User::find($id);
    }

    /**
    * @ignore
    */
    public function notShow(int $id)
    {
        return User::find($id);
    }
}

FormRequest 类可能如下所示：字段描述是从属性 docblock 或类 docblock 的属性注释中获取的。

use Illuminate\Foundation\Http\FormRequest;
/**
 * @property array $fields List of user fields
 */
class UserShowRequest extends FormRequest
{
    /** Is it necessary to show the relationship? */
    public $show_relationships;
    
    public function rules(): array
    {
        return [
            'fields' => 'array'
            'show_relationships' => 'boolean|required'
        ];
    }
}

运行 php artisan swagger:generate -o swagger.json 将生成以下文件

{
    "swagger": "2.0",
    "info": {
        "title": "Laravel",
        "description": "Test",
        "version": "1.0.1"
    },
    "host": "localhost:80",
    "basePath": "/",
    "paths": {
        "/api/user/{id}": {
            "get": {
                "summary": "Return all the details of a user",
                "description": "Returns the user's first name, last name and address Please see the documentation [here](https://example.com/users) for more information",
                "deprecated": true,
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                },
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "type": "integer",
                        "required": true,
                        "description": "User ID"
                    },
                    {
                        "in": "query",
                        "name": "fields",
                        "type": "array",
                        "required": false,
                        "description": "List of user fields"
                    },
                    {
                        "in": "query",
                        "name": "show_relationships",
                        "type": "boolean",
                        "required": true,
                        "description": "Is it necessary to show the relationship?"
                    }
                ]
            }
        },
        "/api/user/{id}/check": {
            "get": {
                "summary": "Check user exist",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                },
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "type": "integer",
                        "required": true,
                        "description": "User ID"
                    }
                ]
            }
        }
    }
}