一、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博客