当前位置：首页 > article >正文

Laravel使用 Swagger

article 2024/10/27 3:08:16

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