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,

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文档（不适用于生产环境！）。你只需要在你的开发环境中向.env文件添加一个名为L5_SWAGGER_GENERATE_ALWAYS的环境变量，并将其设置为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/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 所做的只是将 swagger-php 和 swagger-ui 打包成 Laravel 友好的形式，并试图使其易于提供。有关如何使用 swagger-php 的信息，请查看这里。有关 swagger-php 的良好示例，请查看这里。

Beerpay 上的支持

嘿，兄弟！帮我来几杯🍻吧！