README

此包会扫描您的 Laravel 项目路由并自动为您生成 Swagger 2.0 文档。如果您在控制器的操作中注入表单请求类作为请求验证，它还会为具有它们的每个请求生成参数。它将考虑请求是 GET/HEAD/DELETE 或 POST/PUT/PATCH 请求，并尽可能猜测应生成的参数对象类型。如果您路由包含路径参数，它还会生成路径参数。

安装

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

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

这将注册一个 Artisan 命令，该命令将可供您使用。

您还可以通过在项目根目录中运行 php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" 来覆盖应用程序提供的默认配置，并在新创建的 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"

如果您想更改主机名，可以使用 --host 参数传递主机，例如：php artisan laravel-swagger:generate --host="localhost/laravel"

如果您想应用身份验证（目前仅支持 jwt），可以使用 --auth 参数传递身份验证，例如：php artisan laravel-swagger:generate --auth="jwt"

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

格式选项包括
json
yaml

示例

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

您的示例控制器可能看起来像这样

class UserController extends Controller
{
    public function show(UserShowRequest $request, $id)
    {
        return User::find($id);
    }
}

表单请求类可能看起来像这样

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": "https://",
    "basePath": "\/",
    "paths": {
        "\/api\/user\/{id}": {
            "get": {
                "description": "GET \/api\/user\/{id}",
                "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": ""
                    }
                ]
            },
            ...
        }
    }
}