README

L5 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 注释和生成文档

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

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

使用 OpenApi 3.0 规范

如果您想在使用项目中使用最新的 OpenApi 规范（最初称为 Swagger 规范），您应该

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

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

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

SWAGGER_VERSION=3.0

或在你的 config/l5-swagger.php

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

• 使用这里提供的示例：https://github.com/zircote/swagger-php/tree/3.x/Examples/petstore-3.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 只是按 Laravel 习惯包装了 swagger-php 和 swagger-ui，并试图使其易于服务。有关如何使用 swagger-php 的信息，请 查看此处。有关 swagger-php 的良好示例，请 查看此处。

在 Beerpay 上提供支持

嗨，伙计！请帮我点几杯 🍻！