Laravel 安装 Swagger 扩展及使用教程

什么是 Swagger

Swagger 是一个基于 Open Api 规范的 API 管理工具，通过项目注解的形式自动构建 API 文档，拥有在线调试的功能。提供了多语言的客户端，laravel 中也有相应的扩展包。

选择的扩展包

darkaonline/l5-swagger 是一款针对 laravel 集成开发的扩展包，可以直接使用 laravel 命令行模式进行操作。

packagist的swagger

安装过程

1、通过 composer 安装扩展

composer require darkaonline/l5-swagger

2、添加服务提供者，引导框架运行时加载，AppServiceProvider 中添加

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

或者在 app 配置文件，providers 选项中添加

L5Swagger\L5SwaggerServiceProvider::class

3、配置完成后，通过输入命令 php artisan 查看已经发现该扩展已经加入 laravel 命令列表

swagger命令
4、在浏览器中输入 http://localhost/api/documentation 打开 Swagger UI 面板就可以看到接口信息
swagger ui
5、默认的配置文件在 vendor 的 Swagger 项目中，如果需要修改默认的配置项，可以把配置文件复制出来进行覆写

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

swagger配置文件

注解格式

由于 Swagger 是采用注解的形式进行文档生成，需要按照既定的规则去编写注解，这里只提供一些重要的信息

• API 基础信息
  title：API 名称
  version：API 版本
  description：API 描述
  @OA\Contact：联系方式
  @OA\License：许可协议

<?php
/**
 *
 * @OA\Info(
 *      title="电商API",
 *      version="1.0.1",
 *      description="电商API测试文档",
 *      @OA\Contact(
 *          email="dyuan58@gmail.com"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */
?>

• 接口服务器地址
  url：接口地址

<?php
/**
 *  @OA\Server(
 *      url="http://localhost.dev/api/v2",
 *      description="电商测试环境"
 *  )
 *
 *  @OA\Server(
 *      url="http://localhost.production/api/v1",
 *      description="电商生产环境"
 * )
 */
?>

• 请求
  @OA\Get | @OA\Post：请求类型
  path：请求URI
  tag：归纳相同标签的接口
  summary：接口概要
  description：接口描述
  operationId：接口ID，全局唯一
• 响应
  @OA\Response：响应信息
  response：响应的 http 状态码
  description：响应描述
  @OA\MediaType：响应体
  mediaType：返回格式
  @OA\Schema：定义响应体内的数据
  @OA\Property：定义属性字段（id），数据类型（string）,字段描述（description）
  @OA\JsonContent：因为现在接口通常采用 json 通讯，所以可以直接定义 json 响应格式
  ref：指定可复用的注解模块，TestApi 为模块ID，全局唯一
  @OA\Schema：可复用注解模块，内部可嵌套 Schema

<?php
/**
 * @OA\Get(
 *     path="/test",
 *     tags={"对外服务"},
 *     summary="测试用例",
 *     description="一个测试用的控制器",
 *     operationId="testController",
 *     @OA\Response(
 *         response=500,
 *         description="请求错误示例",
 *         @OA\JsonContent(ref="#/components/schemas/TestApi"),
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="请求成功示例",
 *         @OA\MediaType(
 *             mediaType="application/json",
 *             @OA\Schema(
 *                 @OA\Property(property="id", type="integer", description="主键ID"),
 *                 @OA\Property(property="name", type="string", description="名称"),
 *             ),
 *         )
 *     ),
 * )
 * @OA\Schema(
 *   schema="TestApi",
 *   allOf={
 *     @OA\Schema(
 *       @OA\Property(property="user_id", type="integer", description="用户ID"),
 *       @OA\Property(property="email", type="string", description="email"),
 *     )
 *   }
 * )
 */
?>

生成文档

命令行执行，如果注解格式错误，会报致命错误

php artisan l5-swagger:generate

如果不想每次修改后都手动执行生成命令，可以通过修改 env 文件，添加配置项 L5_SWAGGER_GENERATE_ALWAYS=true
打开 API 文档页面，即可以发现文档生成成功

API文档

点击 "try it out"，可以进行在线调试

try it out

点击 "Execute"，就可以发送调试请求

execute