Swagger php注解常用语法梳理

Swagger php注解常用语法梳理

快速编写你的 RESTFUL API 接口文档工具，通过注释定义接口和模型，可以和代码文件放置一起，也可以单独文件存放。

Swagger 优势

  1. 通过代码注解定义文档，更容易保持代码文档的一致性
  2. 模型复用，减少文档冗余，带来更可靠的文档
  3. 提供客户端访问接口，可以直接调试接口，不需要第三方工具进行调用测试接口
  4. 支持权限认证，等功能

下面详细介绍下Swagger的参数、对象和编写规范；一下是以Laravel 和Swagger为基础进行梳理分享，参考swagger官网文档进行整理，安装和简单使用 >>请这边走

福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全

一、 @OA\Info 声明一个API版本信息

Api版本信息、联系人/组织信息、许可信息

1、基础信息

参数

字段名称类型描述
versionstring需要 Api版本信息。
titlestring需要 API的标题。
descriptionstring参数的简要说明。
termsOfServicestringAPI的服务条款。
contact联系对象API的联系信息。
license许可对象API的许可证信息。
 /**
 * @OA\Info(
 *      version="1.0.0",
 *      title="服务端API",
 *      description="服务端API",
 *      termsOfService="http://example.com/terms/",
 *      @OA\Contact(
 *          url="http://www.example.com/support"
 *          email="miy@126.com",
 *          name="开发支持"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */

2、@OA\Contact 联系信息

API的公开联系信息：参数如下

字段名称类型描述
urlstring联系人/组织的站点。
namestring联系人/组织的名称。
emailstring联系人/组织的邮箱。
 /**
 *@OA\Contact(
 *    url="http://www.example.com/support"
 *    email="miy@126.com",
 *    name="开发支持"
 * ),
 */

3、@OA\License 联系信息

API的公开许可信息：参数如下

字段名称类型描述
urlstring联系人/组织的站点。
namestring联系人/组织的名称。
emailstring联系人/组织的邮箱。
 /**
 * @OA\License(
 *      name="Apache 2.0",
 *      url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *)
 */

二、@OA\Server 服务器新

API 服务器

字段名称类型描述
urlstringApi服务器地址，。
descriptionstringApi服务器描述。
variablesstring联系人/组织的邮箱。
/**
 *  @OA\Server(
 *      url=L5_SWAGGER_CONST_HOST,
 *      description="L5 Swagger OpenApi dynamic host server"
 *  )
 *
 *  @OA\Server(
*      url="https://projects.dev/api/v1",
 *      description="L5 Swagger OpenApi Server"
 * )
 */

三、@OA\Post、Get、Put、Delete 参数描述

字段名称类型描述
tagsboolean接口名称。
pathstring需要。接口请求地址。
summarystring接口简短描述，Ui界面在path后面展示，这个字段应该少于120个字符，对接友好
descriptionstring接口详情描述，接口展开描述接口功能或样例。
operationIdstring友好的操作描述名称，Id在api操作描述中名称唯一，工具库可以使用这个Id标识唯一的操作
security安全对象注明该请求使用哪些安全策略：值列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。该定义覆盖任何已声明的顶层security。要删除顶级安全声明，可以使用空数组。
parameters参数对象适用于此操作的参数列表。如果在路径项目中已经定义了一个参数，新的定义将覆盖它，但是不能删除它。该列表不得包含重复的参数。一个独特的参数是由一个名称和位置的组合来定义的。该列表可以使用引用对象链接到在Swagger对象参数中定义的参数(如果参数巨多可以使用ref引入params对象)。最多可以有一个“body”参数。
responses响应对象需要。执行此操作时返回的可能响应列表。
schemesstring操作的传输协议。值必须是从列表：“http”，“https”，“ws”，“wss”。该值将覆盖Swagger对象schemes定义。
deprecatedboolean声明此操作将被弃用。宣布的操作的使用应该被禁止。默认值是false。
producesstring操作可以产生的类型列表。这将覆盖producesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述
consumesstring该操作可以使用的类型列表。这将覆盖consumesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述。
externalDocs外部文档对象有关此操作的其他外部文档。

MIME类型必须类似如下（包含在 RFC 6838中)

    application/json
    application/xml
    application/x-www-form-urlencoded
    multipart/form-data
    text/plain; charset=utf-8
    text/html
    application/pdf
    image/png

示例

/**
 * 
 * @OA\Get(
 *      path="/users",
 *      operationId="getListOfUsers",
 *      tags={"Users"},
 *      description="Get list of users",
 *      security={{"Authorization-Bearer":{}}}, 
 *      @OA\Parameter(
 *         name="Authorization",
 *         in="header",
 *         required=true,
 *         description="Bearer {access-token}",
 *         @OA\Schema(
 *              type="bearerAuth"
 *         ) 
 *      ), 
 *      @OA\Response(
 *          response=200,
 *          description="Get list of users.",
 *          @OA\JsonContent(type="object",
 *              @OA\Property(property="message", type="string"),
 *              @OA\Property(property="data", type="array",
 *                  @OA\Items(type="object",
 *                      @OA\Property(property="id", type="integer"),
 *                      @OA\Property(property="name", type="string"),
 *                      @OA\Property(property="email", type="string"),
 *                  ),
 *              ),
 *          ),
 *       ),
 *       @OA\Response(response=401, description="Unauthorized"),
 *       @OA\Response(response=404, description="Not Found"),
 * )
 * 
 *
 */

1、@OA\Parameter 参数说明

字段名称类型描述
namestring需要。参数的名称。参数名称区分大小写。
instring需要。参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。
descriptionstring参数的简要说明。这可能包含使用的例子。
typestring参数的类型。取值权限：“string”，“number”，“integer”，“boolean”，“array”，“file”。
requiredboolean确定此参数是否是必需的。其默认值是false。
formatstring参数格式。
default*默认值。

示例：

    /**
     *
     * @OA\Post(
     *      path="/api/login",
     *      tags={"手机验证码登录"},
     *      summary="手机验证码登录",
     *      description="用户登录（手机号+验证码）",
     *
     *      @OA\Parameter(ref="#/components/parameters/authToken"),//这里引入了authToken参数
     *      @OA\RequestBody( 
     *          @OA\MediaType(
     *              *mediaType="application/json",
     *              mediaType="application/x-www-form-urlencoded",
     *              @OA\Schema(ref="#/components/schemas/MobileLogin") //这里引入了手机验证码登录属性模板
     *          )
     *      ),
     *      @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(
     *              ref="#/components/schemas/MsgExport",//这里引入了公共响应模板
     *              example={"code":0,"reason":"接口响应消息","result":{"status":1},"params":{}},
     *          )
     *       ),
     *
     * )
     *如果有多个参数的话且复用度较高，可以独立设置params，然后引用 
     * @OA\Parameter(
    *     in="header",
    *     name="authToken",
    *     description="测试HeaderToken",
    *     required=true,
    *     @OA\Schema(
    *          type="string"
    *     )
    * ),
     */

2、@OA\Response 参数描述

字段名称类型描述
descriptionstring必填 响应的简短描述。。
schema模式对象响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。
headers标题对象与响应一起发送的标题列表。
examples示例对象响应消息的一个例子。

示例：

    /*
     * @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(ref="#/components/schemas/MsgExport")
     *       )
     */

3、@OA\Schema

/**
*定义可以复用的响应模板：
*
*  @OA\Schema(
*       schema="MsgExport",
*       required={"code","reason"},
*       @OA\Property(
*            property="code",
*            type="integer",
*            format="int32",
*            description="状态码"
*       ),
*       @OA\Property(
*            property="reason",
*            type="string",
*            description="提示消息"
*            ),
*       @OA\Property(
*            property="result",
*            type="array",
*            description="请求结果",
*            @OA\Items(
*                 @OA\Property(
*                      property="id",
*                      type="integer",
*                      description="ID"
*                  ),
*            )
*       ),
*       @OA\Property(
*            property="params",
*            type="array",
*            description="其他二外参数",
*       ),
* ),
*
*定义手机验证码登录属性模板：
*@OA\Schema(
*      description:"短信验证码登录属性",
*      schema="MobileLogin",
*      required={"mobile", "code","codeType"},
*      example={"mobile":"18913556768","code":"123123","codeType":1},
*      @OA\Property(
*          property="mobile",
*          type="string",
*          description="手机号"
*      ),
*      @OA\Property(
*          property="code",
*          type="string",
*          description="在验证码"
*      ),
*     @OA\Property(
*          property="codeType",
*          type="integer",
*          description="验证码类型",
*          default=1,
*      ),
* )
*/

4、@OA\SecurityScheme 鉴权

普通apiKey鉴权

/**
 * @OA\SecurityScheme(
 *     type="apiKey",
 *     description="全局添加API Token鉴权",
 *     name="authorization",
 *     in="header",
 *     securityScheme="Authorization-Bearer"
 * )
 *
 */

示例演示渲染如下：

image.png

二、不分组接口

项目开发中接口众多，需要对相同业务类型进行分组显示，否则就是这样的：

如果有个几十个接口的话，页面可想而知

image.png

三、分组接口

swagger-php 提供了tag,上面的情况是没有弄清楚tag的作用，才导致接口零散无须

在添加接口注解的时候合理充分的使用tag可以是接口测试页面变得简洁有序更友好：

1.定义顶层Tag

可以在控制器的顶层定义一个父级tag，添加业务描述和接口简介

/**
 * 处理登录相关的逻辑
 *
 * Class LoginController
 * @package App\Http\Controllers\Api
 * @OA\Tag(
 *     name="登录鉴权",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 * @OA\Tag(
 *     name="分组1",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 * @OA\Tag(
 *     name="分组2",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 */

2.接口tag

接口定义和注解的时候添加tag，下面定义了三个tag，每一个接口可以属于多个tag分组，这里为了演示将接口进行了分组：定义分组（登录鉴权，分组1，分组2）；未定义的分组（分组3）


    /**    
     * @OA\Get(
     *      path="/api/pub/key",
     *      operationId="apiLoginKey",
     *      tags={"登录鉴权","分组1"},
     *      summary="秘钥获取",
     *      description="发送手机验证妈的时候对手机号进行加密，进行发送",
     *      @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(ref="#/components/schemas/MsgExport")
     *       )
     * )
     *
     *
     * @OA\Get(
     *      path="/api/login/status",
     *      tags={"登录鉴权","分组1","分组3"},
     *      summary="登录状态",
     *      description="Returns project data",
     *     @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(ref="#/components/schemas/MsgExport")
     *       )
     * )
     *
     * @OA\Post(
     *      path="/api/login",
     *      tags={"登录鉴权","分组2","分组3"},
     *      summary="手机验证码登录",
     *      description="用户登录（手机号+验证码）",
     *      @OA\Parameter(ref="#/components/parameters/authToken"),
     *      @OA\RequestBody(
     *          @OA\MediaType(
     *              mediaType="application/x-www-form-urlencoded",
     *              @OA\Schema(ref="#/components/schemas/MobileLogin")
     *          )
     *      ),
     *      @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(
     *              ref="#/components/schemas/MsgExport",
     *              example={"code":0,"reason":"接口响应消息","result":{"status":1},"params":{}},
     *          )
     *       ),
     *
     * )
     *
     * @OA\Get(
     *      path="/api/login/logout",
     *      tags={"登录鉴权","分组2"},
     *      summary="登出",
     *      description="用户登出",
     *     @OA\Response(
     *          response=200,
     *          description="successful operation",
     *       )
     * )
     */

页面渲染结果如下：

定义的分组顶部显示，未定义的分组3，最后显示：

如何合理的规划和使用tag进行分组需要根据实际业务情况进行设计

image.png

福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mfbz.cn/a/772568.html

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

Spring Boot中使用SpringEvent组件

Spring Boot中使用SpringEvent组件

Spring的事件机制是基于观察者模式的实现，主要由以下三个部分组成： 事件（Event）：事件是应用中发生的重要事情，通常是一个继承自ApplicationEvent的类。 事件发布器（Publisher）&…
阅读更多...
ubuntu使用官方deb文件安装指定版本cuda失败，总是装成最新版

ubuntu使用官方deb文件安装指定版本cuda失败，总是装成最新版

之前安装过最新版的cuda，之后想换用旧版，但是按照官网的说明，sudo apt-get -y install cuda后总是装成最新版的。 解决方法： 最后一步使用sudo apt-get -y install cuda-x-x，直接指定你要安装的cuda的版本号。
阅读更多...
python作业一

python作业一

1. #A. num int(input("请输入要打印的层数:")) for n in range(1, num1):s ""for i in range(1, n1):s f"{i}" " "print(s)#B. num int(input("请输入要打印的层数:")) for i in range(num1, 0, -1):s" "f…
阅读更多...
springcloud+vue项目，controller层接口返回json数据，前端可以接收到数据，但浏览器“F12--＞网络--＞响应“显示为空的问题处理

springcloud+vue项目，controller层接口返回json数据，前端可以接收到数据，但浏览器“F12--＞网络--＞响应“显示为空的问题处理

1.显示为空的场景 SharetekR(access_tokeneyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpblR5cGUiOiJsb2dpbiIsImxvZ2luSWQiOiJQQzoxODA1ODA4ODc1MjUwMTIyNzUyIiwicm5TdHIiOiJrZEoxV05CV3NBSUdYb05TbktSU3kzOGNuSnk3c3FRTSIsInVzZXJJZCI6MTgwNTgwODg3NTI1MDEyMjc1MiwidXNlck5h…
阅读更多...
分布式数据库HBase:从零开始了解列式存储

分布式数据库HBase:从零开始了解列式存储

在接触过大量的传统关系型数据库后你可能会有一些新的问题: 无法整理成表格的海量数据该如何储存? 在数据非常稀疏的情况下也必须将数据存储成关系型数据库吗? 除了关系型数据库我们是否还有别的选择以应对Web2.0时代的海量数据? 如果你也曾经想到过这些问题, 那么HBase将是…
阅读更多...
25届最近5年华北电力大学自动化考研院校分析

25届最近5年华北电力大学自动化考研院校分析

华北电力大学（北京保定） 目录 一、学校学院专业简介 二、考试科目指定教材 三、近5年考研分数情况 四、近5年招生录取情况 五、最新一年分数段图表 六、初试大纲复试大纲 七、学费&奖学金&就业方向 一、学校学院专业简介 二、考试科目指…
阅读更多...
【C语言】刷题笔记 Day2

【C语言】刷题笔记 Day2

【笔记】 【1】局部变量不初始化，默认放的随机值。 1 int n0; 2 scanf("%d",&n); //13.141 【2】这里虽然输入的是一个浮点数，但是只取整数部分。 【3】3.156e7 表示的是3.156*10的7次方。 【4】多组输入，保存和不保存…
阅读更多...
关于Wav2Lip配置实现

关于Wav2Lip配置实现

模型介绍 Wav2Lip是一种先进的深度学习模型，旨在将音频波形直接转换为面部动画，尤其关注于唇部动作的生成与同步。这一技术的核心在于其能够利用输入的语音信号，生成与之高度匹配的嘴唇动作，从而实现逼真的语音驱动数字人物动画效…
阅读更多...
docker初始化运行mysql容器时自动导入数据库存储过程问题

docker初始化运行mysql容器时自动导入数据库存储过程问题

问题：用navicat导出的数据库脚本，在docker初始化运行mysql容器时，导入到存储过程时出错。 ERROR 1064 (42000) at line 2452: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for t…
阅读更多...
DataWhale-吃瓜教程学习笔记 (六）

DataWhale-吃瓜教程学习笔记 (六）

学习视频**：第4章-决策树_哔哩哔哩_bilibili 西瓜书对应章节： 第五章 5.1；5.2；5.3 文章目录 MP 神经元- 感知机模型 （分类模型）-- 损失函数定义--- 感知机学习算法 - 随机梯度下降法 - 神经网络需要解决的问…
阅读更多...
2024年显著性检测部分论文及代码汇总（3）

2024年显著性检测部分论文及代码汇总（3）

ICML Size-invariance Matters: Rethinking Metrics and Losses for Imbalanced Multi-object Salient Object Detection code Abstacrt：本文探讨了显著性检测中评价指标的尺寸不变性，尤其是当图像中存在多个大小不同的目标时。作者观察到，…
阅读更多...
解决Python爬虫开发中的数据输出问题：确保正确生成CSV文件

解决Python爬虫开发中的数据输出问题：确保正确生成CSV文件

引言 在大数据时代，爬虫技术成为获取和分析网络数据的重要工具。然而，许多开发者在使用Python编写爬虫时，常常遇到数据输出问题，尤其是在生成CSV文件时出错。本文将详细介绍如何解决这些问题，并提供使用代理IP和多线程…
阅读更多...
开始尝试从0写一个项目--前端（一）

开始尝试从0写一个项目--前端（一）

基础项目构建 创建VUE初始工程 确保自己下载了node.js和npm node -v //查看node.js的版本 npm -v //查看npm的版本 npm i vue/cli -g //安装VUE CLI 创建 以管理员身份运行 输入：vue ui 就会进入 点击创建 自定义项目名字，选择npm管理 结…
阅读更多...
C++ 智能指针内存泄漏问题

C++ 智能指针内存泄漏问题

shared_ptr相互嵌套导致循环引用 代码示例 #include <iostream> #include <memory> using namespace std;class B;class A { public:std::shared_ptr<B> b_ptr;~A() { std::cout << "A destroyed\n"; } };class B { public:std::shared_pt…
阅读更多...
【前端项目笔记】8 订单管理

【前端项目笔记】8 订单管理

订单管理 效果展示&#xff1a; 在开发功能之前先创建分支order cls 清屏 git branch 查看所有分支&#xff08;*代表当前分支&#xff09; git checkout -b order 新建分支order git push -u origin order 将本地的当前分支提交到云端仓库origin中命名为order 通过路由方式…
阅读更多...
014-GeoGebra基础篇-快速解决滑动条的角度无法输入问题

014-GeoGebra基础篇-快速解决滑动条的角度无法输入问题

有客户反馈&#xff0c;他的Geogebra一直有个bug&#xff0c;那就是输入角度最大值时总不按照他设定的展示&#xff0c;快被气炸了~ 目录 一、问题复现&#xff08;1&#xff09;插入一个滑动条&#xff08;2&#xff09;选择Angle&#xff08;3&#xff09;输入90&#xff0c;…
阅读更多...
|从零搭建网络| VisionTransformer网络详解及搭建

|从零搭建网络| VisionTransformer网络详解及搭建

&#x1f31c;|从零搭建网络| VisionTransformer系列网络详解及搭建&#x1f31b; 文章目录 &#x1f31c;|从零搭建网络| VisionTransformer系列网络详解及搭建&#x1f31b;&#x1f31c; 前言 &#x1f31b;&#x1f31c; VIT模型详解 &#x1f31b;&#x1f31c; VIT模型架…
阅读更多...
Buuctf之不一样的flag（迷宫题）

Buuctf之不一样的flag（迷宫题）

首先&#xff0c;进行查壳无壳&#xff0c;32bit&#xff0c;丢进ida32中进行反编译进入main函数&#xff0c;对其进行分析&#xff0c;可以在一旁打上注释&#xff0c;这边最关键的一个点就是&#xff0c;需要联想到这是一个迷宫题&#xff0c;很小的迷宫题&#xff0c;迷宫就…
阅读更多...
Kindling-OriginX 在快手 Staging 环境的异常诊断效果分享

Kindling-OriginX 在快手 Staging 环境的异常诊断效果分享

业务可用性问题的快速诊断&#xff0c;历来是行业互联网公司面临的重大挑战&#xff0c;快手也不外如是。Kindling-OriginX的体系化设计理念快速打动了我们的工程师。快手随即开始了内部真实业务的验证落地&#xff1b;落地过程中&#xff0c;Kindling-OriginX能高效覆盖大部分…
阅读更多...
classin视频下载提取为mp4教程

classin视频下载提取为mp4教程

最近在上classin网课&#xff0c;无奈网课视频要过期了&#xff0c;所以想保存下来&#xff01; 下面介绍提取的教程 我们可以绕过最开始的握手&#xff0c;就是先播放了一段时间后&#xff0c;再打开抓包&#xff0c;回到Classin播放后&#xff0c;就可以获得网课链接了 直接打…
阅读更多...
最新文章

Copyright @ 2022~2023

友情链接： 我的编程经验分享 一条长河网 尧图网站开发 尧图建网站