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来生成文档。或者，你可以在.env文件中将L5_SWAGGER_GENERATE_ALWAYS设置为true，以便自动生成文档。请确保你的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，并通过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

请遵循问题#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上的支持

嘿，兄弟！请帮我喝一杯🍻！