一、Swagger 基础
1、 什么是Swagger
Swagger 是一个基于 Open Api 规范的 API 管理工具，通过项目注解的形式自动构建 API 文档，拥有在线调试的功能。提供了多语言的客户端，laravel 中也有相应的扩展包。
二、Swagger 接入
1，用compser导入l5-swagger包
composer require "darkaonline/l5-swagger"
2，生成配置及初始化文件
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
执行上述命令后，config下面会生成文件l5-swagger.php
Resources/views下面也会生成vendor文件夹
3，注册swagger
打开config/app.php，在providers数组中添加：
\L5Swagger\L5SwaggerServiceProvider::class
4，配置swagger
defaults>paths>excludes：
这个参数用来指定在执行 php artisan l5-swagger:generate 时，需要忽略的文件。
scanOptions>pattern：
用来配置要扫描并生成文档的文件类型。
示例：
'defaults' => [ 'paths' => [ 'excludes' => [ 'App\Http\Controllers\Api\Helpers\ExceptionReport', ], ],
], 'scanOptions' => [ 'pattern' => ['*Controller.php', '*Schema.php'],
], 5，生成swagger文档的方式
php artisan l5-swagger:generate
这个每次注释更新之后，都需要执行一次命令来重新生成api文档，
在.env文件下面配置L5_SWAGGER_GENERATE_ALWAYS=true
配置后，无需手动生成api文档，直接访问api文档地址即可
6，访问api文档
访问地址：域名/api/documentation
host比如下图这里的api.apidoc.com：本地配置的域名指向项目public这个路径
三，注解介绍
由于 Swagger 是采用注解的形式进行文档生成，需要按照既定的规则去编写注解，这里只提供一些重要的信息
API 基础信息
title：API 名称
version：API 版本
description：API 描述
@OA\Contact：联系方式
@OA\License：许可协议
请求
@OA\Get | @OA\Post：请求类型
path：请求URI
tag：归纳相同标签的接口
summary：接口概要
description：接口描述
operationId：接口ID，全局唯一
@OA\Parameter:接收的参数是来自requestHeader中，即请求头。GET、\POST都适用
@OA\RequestBody:接收的参数是来自requestBody中，即请求体。主要用来接收前端传递给后端的json字符串中的数据的，所以只能发送POST请求
匹配path中的数值则 in path 查询 in query
这里是支持多文件上传，删除一个就是单文件上传
/**
* @OA\Post(summary="上传文件",path="/api/upload/file/{type}",tags={"Upload"},description="上传文件",
* security={{"Bearer":{} }},
* @OA\Parameter(name="type",in="path",required=true,description="类型"),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="multipart/form-data",
* @OA\Schema(
* @OA\Property(property="file",type="file",description="文件"),
* @OA\Property(property="file2",type="file",description="文件2")
* )
* )
* ),
* @OA\Response(response="200",description="获取成功",
* @OA\MediaType(mediaType="application/json",
* @OA\Schema(
* @OA\Property(property="img_url",description="路径",type="string"),
* @OA\Property(property="original_name",description="原始名称",type="string"),
* )
* )
* )
* )
*/
public function postUploadFile($case){
$file = $this->request->file('file');
//逻辑
}
响应
@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
四，附加，更加详细的注解说明可以参考文档：
https://learnku.com/laravel/t/7430/how-to-write-api-documents-based-on-swagger-php
Laravel Swagger 使用完整教程-CSDN博客
