README

L5 Swagger - 为您的Laravel项目简化OpenApi或Swagger规范。

Swagger 2.0 for Laravel >=5.1

此包是Swagger-php和swagger-ui的包装器，它们已适配以与Laravel 5协同工作。

安装

您可以通过运行以下命令将L5-Swagger的配置和视图文件发布到您的项目中：

$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

对于Laravel >=5.5，无需手动将L5SwaggerServiceProvider添加到配置中。它使用包自动发现功能。如果您使用的是>=5.5，请跳过此步骤。

打开您的AppServiceProvider（位于app/Providers），并在register函数中添加以下行

$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);

或打开您的config/app.php，并在providers部分添加以下行

L5Swagger\L5SwaggerServiceProvider::class,

您可以在/api/documentation端点访问您的文档。

Swagger/OpenApi注释和生成文档

为了生成您的API的Swagger/OpenApi文档，Swagger提供了一套注释来声明和操作输出。这些注释可以添加到您的控制器、模型，甚至是一个单独的文件中。例如，可以在这里找到OpenApi注释，可以在这里找到Swagger注释。更多信息请查看Swagger的"pet store"示例或Swagger OpenApi规范。

添加注释后，您可以通过运行php artisan l5-swagger:generate来生成文档。或者，您可以将L5_SWAGGER_GENERATE_ALWAYS设置为true在您的.env文件中，这样您的文档将自动生成。请确保您的config/l5-swagger.php中的设置完整。

我仍然在使用Swagger @SWG注释

如果您在项目中仍然使用Swagger @SWG注释，则应该

• 通过运行在您的项目的composer中显式要求swagger-php版本2.*

composer require 'zircote/swagger-php:2.*'

• 在您的.env文件中将环境变量SWAGGER_VERSION设置为2.0

SWAGGER_VERSION=2.0

或在您的config/l5-swagger.php

'swagger_version' => env('SWAGGER_VERSION', '2.0'),

使用Swagger UI与Passport

使用Swagger-php构建和测试基于Laravel的API的最简单方法是使用Passport的CreateFreshApiToken中间件。这个中间件是Laravel核心中内置的，它将一个cookie添加到所有响应中，并且该cookie通过Passport的TokenGuard认证所有后续请求。

要开始，首先将L5-Swagger的配置和视图文件发布到您的项目中

$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

接下来，编辑您的config/l5-swagger.php配置文件。找到l5-swagger.routes.middleware部分，并将以下中间件列表添加到api路由

'api' => [
  \App\Http\Middleware\EncryptCookies::class,
  \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
  \Illuminate\Session\Middleware\StartSession::class,
  \Illuminate\View\Middleware\ShareErrorsFromSession::class,
  \App\Http\Middleware\VerifyCsrfToken::class,
  \Illuminate\Routing\Middleware\SubstituteBindings::class,
  \Laravel\Passport\Http\Middleware\CreateFreshApiToken::class,
  'auth',
]

技巧

L5_SWAGGER_GENERATE_ALWAYS

我发现启用其中一个有用的设置是l5-swagger.generate_always，这将导致每次您加载Swagger UI时都重新生成Swagger文档（不适用于生产使用！）。要启用此功能，只需在您的开发环境中将名为L5_SWAGGER_GENERATE_ALWAYS的环境变量添加到.env文件中，并将其设置为true即可。

oauth2 + passport = Bearer <token>

按照问题#57中的说明操作。

5.0版本中的更改

• Swagger UI 3.
• 配置更改。
• 已删除资产依赖。现在从composer包中包含。
• 查看迁移

4.0版本中的更改

• Laravel 5.4支持

3.2.1版本中的更改

• 支持路由中间件 (#43) (@tantam)

3.2版本中的更改

• 允许在生成过程中更改swagger基本路径
• 允许在配置中定义可以在后续注解中使用的常量
• 修复了L5.3及PHP >= 5.6的测试
• 更新swagger UI到2.1.5

3.1版本中的更改

• 将闭包路由移动到控制器并命名（感谢 @bbs-smuller #19）
• 添加了重命名生成的API .json文件名的选项

3.0版本中的更改

• 更精确的命名和结构化配置
• Swagger UI - v2.1.4
• 测试

从2.0迁移到3.0

• 将您的 AppServiceProvider 中的 $this->app->register('\Darkaonline\L5Swagger\L5SwaggerServiceProvider'); 替换为 $this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);，或在您的 config/app.php 文件中添加 \L5Swagger\L5SwaggerServiceProvider::class 行
• 运行 l5-swagger:publish-config 以发布新配置并按需进行更改
• 删除 public/vendor/l5-swagger 目录
• 删除 resources/views/vendor/l5-swagger 目录
• 运行 l5-swagger:publish-assets 以发布新的swagger-ui资产
• 运行 l5-swagger:publish-views 以发布新视图

从3.0|4.0迁移到5.0

• 删除 config/l5-swagger.php 文件（如有需要，请备份）
• 删除 public/vendor/l5-swagger 目录
• 删除 resources/views/vendor/l5-swagger 目录
• 运行 l5-swagger:publish 以发布新的swagger-ui视图和配置
• 编辑您的 config/l5-swagger.php 文件

配置

对于版本 < 5.5

• 运行 l5-swagger:publish 以发布所有内容
• 运行 l5-swagger:publish-config 以发布配置（config/l5-swagger.php）
• 运行 l5-swagger:publish-assets 以将swagger-ui发布到您的public文件夹（public/vendor/l5-swagger）
• 运行 l5-swagger:publish-views 以发布视图（resources/views/vendor/l5-swagger） - 仅适用于版本 <= 4.0

对于所有版本

• 运行 l5-swagger:generate 以生成文档或将配置或.env文件中的 generate_always 参数设置为 true

Swagger-php

实际的Swagger规范超出了本包的范围。L5-Swagger所做的只是以Laravel友好的方式打包swagger-php和swagger-ui，并尝试使其易于提供。有关如何使用swagger-php的信息，请查看这里。有关swagger-php应用的示例，请查看这里。

在Beerpay上提供支持

嘿，兄弟！帮我几个🍻！