什么是 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
