README

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

Laravel版本

到目前为止，此分支已测试以下Laravel版本

• 6.16.0

关于

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

需要注意的是，此库倾向于明确。即使它们有默认值，它也会选择包含键。例如，它会选择说明路由有一个已弃用的值为false，而不是将其省略。我相信这通过不省略重要信息使阅读文档变得更容易。用户可以选择在之后清理文件以省略默认值。

安装

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

如果您正在运行Laravel版本<5.5以下，请确保将Mtrajano\LaravelSwagger\SwaggerServiceProvider::class添加到config/app.php中的providers数组中。

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

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

用法

生成swagger文档很简单，只需在项目根目录中运行php artisan laravel-swagger:generate。请注意，该命令将简单地打印输出到您的控制台。如果要将文档保存到文件中，可以重定向输出如下：php artisan laravel-swagger:generate > swagger.json

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

默认情况下，laravel-swagger以JSON格式打印文档，如果要以YAML格式打印，可以使用--format标志覆盖格式。如果选择这样做，请确保已安装yaml扩展。

格式选项有
json
yaml

示例

假设您有一个路由/api/users/{id}，它映射到UserController@show

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

/**
 * 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
 */
class UserController extends Controller
{
    public function show(UserShowRequest $request, $id)
    {
        return User::find($id);
    }
}

FormRequest类可能如下所示

class UserShowRequest extends FormRequest
{
    public function rules()
    {
        return [
            'fields' => 'array'
            'show_relationships' => 'boolean|required'
        ];
    }
}

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

{
    "swagger": "2.0",
    "info": {
        "title": "Laravel",
        "description": "Test",
        "version": "1.0.1"
    },
    "host": "http:\/\/localhost",
    "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": ""
                    },
                    {
                        "in": "query",
                        "name": "fields",
                        "type": "array",
                        "required": false,
                        "description": ""
                    },
                    {
                        "in": "query",
                        "name": "show_relationships",
                        "type": "boolean",
                        "required": true,
                        "description": ""
                    }
                ]
            },
            ...
        }
    }
}