在 Laravel 项目中集成 Swagger 扩展包为 Laravel API 生成接口文档并对接口进行测试
由 学院君 创建于1年前, 最后更新于 1年前
版本号 #1
除了上篇介绍的 API 文档生成器扩展包之外，我们还可以基于著名的 Swagger 在 Laravel 项目中为 API 接口生成文档。
Swagger 是一个开源的、用于简化 API 开发的工具集，这些工具集涵盖了 API 开发的整个生命周期，从设计到文档、从测试到部署。
Swagger vs OpenAPI
在介绍基于 Swagger 工具集生成 API 文档之前，我们有必要先了解下 Swagger 与 OpenAPI 的区别，一句话来概括，就是 OpenAPI 是规范，而 Swagger 是实现这些规范的工具集。
最早，OpenAPI 规范和 Swagger 工具集都属于 Swagger 项目，Swagger 在 2010 年诞生之际，是一个简单的、用于设计 RESTful API 的开源规范，然后为了更好的实现以及可视化规范中定义的 API，又诞生了 Swagger UI、Swagger Editor、Swagger Codegen 等开源工具，随着包含规范和这些开源工具的 Swagger 项目的流行，逐渐创建起了一个庞大的、社区驱动的工具生态系统。
2015 年，Swagger 项目被 SmartBear Software 收购，Swagger 规范被捐赠给 Linux 基金会并被重命名为 OpenAPI 规范(简称 OAS)，正式用于标准化 REST API 的描述，同时创建 OpenAPI Initiative 组织以便以开放透明的方式来指导 OpenAPI 的开发(目前该组织包括微软、Google、IBM、以及 SmartBear Software 等30多个成员)。这样一来，Swagger (剥离了规范的 Swagger 工具集)也顺理成章成为了可以在 API 整个开发周期充分 OAS 功能的最流行的工具集。
目前 Swagger 提供的工具集包括以下这些：
Swagger Editor：Swagger 编辑器让你可以通过 YAML 格式在浏览器中编辑遵循 OpenAPI 规范的 API 文档并实时预览；
Swagger UI：Swagger UI 是一个 HTML、CSS 和 JavaScript 资源集合，可用于动态生成符合 OpenAPI 规范的 API 文档；
Swagger Codegen：允许在给定符合 OAS 的 API 情况下生成 API SDK、服务器存根以及对应文档；
Swagger Parser：Java 语言中解析 OpenAPI 定义的独立库；
Swagger Core：用于创建、消费、处理 OpenAPI 定义的 Java 相关库；
Swagger Inspector (免费)：用于验证 API & 通过已存在 API 生成 OpenAPI 定义的 API 测试工具；
SwaggerHub(包含免费和商业版本)：用于团队处理 OpenAPI 的 API 设计和文档工具。
Swagger 工具集只是由 OpenAPI 规范原先的创建者开发的工具集，但是并不是唯一实现 OpenAPI 的工具集，还有很多其他的支持该规范的 API 设计、文档、测试、管理、监控实现方案(主要是 OpenAPI 2.0 及上版本)，你可以在这里找到它们：OpenAPI 规范实现方案。
注：OpenAPI 3.0 版本是 Swagger API 规范捐赠给 OpenAPI Initiative 后官方发布的首个版本。后面学院君的介绍和使用也是基于这个最新版本。
基于 Swagger 扩展包生成 API 文档
在 PHP 中，我们可以基于 swagger-php 扩展包通过 doctrine 注解为 RESTful API 生成 OpenAPI 文档，当然，在 Laravel 项目也可以使用这个扩展包，不过为了快速集成，我们还可以使用基于该扩展包封装的适用于 Laravel 框架的 L5 Swagger 扩展包。
安装扩展包
在使用 L5 Swagger 扩展包之前，需要通过 Composer 安装它，对于 Laravel 5.8 版本，对应的安装指令如下：
composer require "darkaonline/l5-swagger:5.8.*"
如果是其他 Laravel 版本，对应的安装指令如下：
Laravel
Swagger UI
OpenAPI Spec compatibility
L5-Swagger5.7.x
3
3.0, 2.0
composer require "darkaonline/l5-swagger:5.7.*"
5.6.x
3
2.0
composer require "darkaonline/l5-swagger:5.6.*"
5.5.x
3
2.0
composer require "darkaonline/l5-swagger:5.5.*"
5.4.x
3
2.0
composer require "darkaonline/l5-swagger:5.4.*"
5.4.x
2.2
1.1, 1.2, 2.0
composer require "darkaonline/l5-swagger:~4.0"
5.3.x
2.2
1.1, 1.2, 2.0
composer require "darkaonline/l5-swagger:~3.0"
5.2.x
2.2
1.1, 1.2, 2.0
composer require "darkaonline/l5-swagger:~3.0"
5.1.x
2.2
1.1, 1.2, 2.0
composer require "darkaonline/l5-swagger:~3.0"
安装完成后，使用如下 Artisan 命令发布该扩展包的配置和视图文件：
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
然后在 .env 中设置 Laravel 项目 API 接口的 URL 根路径：
L5_SWAGGER_CONST_HOST=http://todo.test/dingoapi
取消 config/l5-swagger.php 配置文件中 security.passport 配置项的注释：
// Open API 3.0 support
'passport' => [ // Unique name of security