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/jsonapplication/xmlapplication/x-www-form-urlencodedmultipart/form-datatext/plain; charset=utf-8text/htmlapplication/pdfimage/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.mzph.cn/news/867396.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

C++(Qt)-GIS开发-QGraphicsView显示瓦片地图简单示例

C++(Qt)-GIS开发-QGraphicsView显示瓦片地图简单示例

C(Qt)-GIS开发-QGraphicsView显示瓦片地图简单示例 文章目录 C(Qt)-GIS开发-QGraphicsView显示瓦片地图简单示例1、概述2、实现效果3、主要代码4、源码地址 更多精彩内容👉个人内容分类汇总 👈👉GIS开发 👈 1、概述 支持多线程加…
阅读更多...
【十三】图解 Spring 核心数据结构：BeanDefinition 其二

【十三】图解 Spring 核心数据结构：BeanDefinition 其二

图解 Spring 核心数据结构：BeanDefinition 其二 概述 前面写过一篇相关文章作为开篇介绍了一下BeanDefinition，本篇将深入细节来向读者展示BeanDefinition的设计，让我们一起来揭开日常开发中使用的bean的神秘面纱，深入细节透彻理解…
阅读更多...
第9章 项目总结01：项目流程，每个模块的介绍

第9章 项目总结01：项目流程，每个模块的介绍

1 请介绍一下你的项目 学成在线项目是一个B2B2C的在线教育平台，本项目包括了用户端、机构端、运营端。 核心模块包括：内容管理、媒资管理、课程搜索、订单支付、选课管理、认证授权等。 下图是项目的功能模块图： 项目采用前后端分离的技…
阅读更多...
去除gif动图背景的工具网站

去除gif动图背景的工具网站

选择视频或GIF - 取消屏幕 (unscreen.com)https://www.unscreen.com/upload
阅读更多...
24-7-6-读书笔记（八）-《蒙田随笔集》[法]蒙田 [译]潘丽珍

24-7-6-读书笔记（八）-《蒙田随笔集》[法]蒙田 [译]潘丽珍

文章目录 《蒙田随笔集》阅读笔记记录总结 《蒙田随笔集》 《蒙田随笔集》蒙田（1533-1592），是个大神人，这本书就是250页的样子，但是却看了好长好长时间，体会还是挺深的，但看的也是不大仔细&…
阅读更多...
【TORCH】绘制权重分布直方图，权重torch.fmod对torch.normal生成的随机数进行取模运算

【TORCH】绘制权重分布直方图，权重torch.fmod对torch.normal生成的随机数进行取模运算

要绘制上述代码中权重初始化的分布，可以分别展示每一层初始化权重的直方图。我们将用 torch.fmod 对 torch.normal 生成的随机数进行取模运算，确保权重值在 -2 到 2 之间。 含义解释 torch.normal(0, init_sd, size...)：生成服从均值为 0、…
阅读更多...
以黑盒与白盒的角度分析和通关xss-labs(XSS漏洞类型与总结)

以黑盒与白盒的角度分析和通关xss-labs(XSS漏洞类型与总结)

目录 目录 前言 XSS漏洞的总结和梳理 1.第一关(基础palyload) 黑盒测试 白盒测试 2.第二关(闭合) 黑盒测试 白盒测试 3.第三关(字符转义) 黑盒测试 白盒测试 4.第四关(字符过滤或替换) 黑盒测试 白盒测试 5.第五关(关键词替换) 黑盒测试 白盒测试 6.第六关(…
阅读更多...
el-table实现固定列，及解决固定列导致部分滚动条无法拖动的问题

el-table实现固定列，及解决固定列导致部分滚动条无法拖动的问题

一、el-table实现固定列 当数据量动态变化时&#xff0c;可以为 Table 设置一个最大高度。 通过设置max-height属性为 Table 指定最大高度。此时若表格所需的高度大于最大高度&#xff0c;则会显示一个滚动条。 <div class"zn-filter-table"><!-- 表格--…
阅读更多...
AI对于高考和IT行业的深远影响

AI对于高考和IT行业的深远影响

目录 AI对IT行业的冲击及深远影响1. 工作自动化2. 新的就业机会3. 行业融合4. 技术升级和创新5. 数据的重要性 IT行业的冬天要持续多久&#xff1f;大学的软件开发类专业是否还值得报考&#xff1f;其他问题IT行业是否都是加班严重&#xff1f;35岁后就业困难是否普遍现象&…
阅读更多...
基于TCP的在线词典系统(分阶段实现)

基于TCP的在线词典系统(分阶段实现)

1.功能说明 一共四个功能&#xff1a; 注册 登录 查询单词 查询历史记录 单词和解释保存在文件中&#xff0c;单词和解释只占一行, 一行最多300个字节&#xff0c;单词和解释之间至少有一个空格。 2.功能演示 3、分阶段完成各个功能 3.1 完成服务器和客户端的连接 servic…
阅读更多...
springcloud-alibba之FeignClient

springcloud-alibba之FeignClient

代码地址&#xff1a;springcloud系列: springcloud 组件分析拆解 1.FeignClient的集成 springboot版本&#xff1a;3.1.5 springcloud组件版本&#xff1a;2022.0.4 nacos客户端的版本&#xff1a;2.3.2 1.引pom 这里引入了nacos和feginclient的版本 <dependency>…
阅读更多...
【MySQL】事务四大特性以及实现原理

【MySQL】事务四大特性以及实现原理

事务四大特性 原子性&#xff08;Atomicity&#xff09; 事务中的所有操作要么全部完成&#xff0c;要么全部不执行。如果事务中的任何一步失败&#xff0c;整个事务都会被回滚&#xff0c;以保持数据的完整性。 一致性&#xff08;Consistency&#xff09; 事务应确保数据库…
阅读更多...
机器学习——决策树及其可视化

机器学习——决策树及其可视化

1、决策树概念 顾名思义&#xff0c;决策树是利用数据结构中树结构来进行判断&#xff0c;每一个结点相当于一个判断条件&#xff0c;叶子结点即是最终的类别。以鸢尾花为例&#xff0c;可以得到如下的决策树&#xff1a; 2、决策树分类的依据是什么&#xff1f; 根据前面分…
阅读更多...
跨越语言的界限：Vue I18n 国际化指南

跨越语言的界限：Vue I18n 国际化指南

前言 &#x1f4eb; 大家好&#xff0c;我是南木元元&#xff0c;热爱技术和分享&#xff0c;欢迎大家交流&#xff0c;一起学习进步&#xff01; &#x1f345; 个人主页&#xff1a;南木元元 目录 国际化简介 vue-i18n 安装和配置 创建语言包 基本使用 切换语言 动态翻…
阅读更多...
CTFShow的RE题（二）

CTFShow的RE题（二）

逆向5 附件无后缀&#xff0c;查一下是zip&#xff0c;解压得到一个exe一个dll文件。 往下继续看 但也根进去看看 发现是在加载的dll文件 还有一个返回时调用的函数 发现是打印函数 根据以往的经验应该是要跳转到这里&#xff0c;动调一下。 发现exe链接了dll&#xff0c;…
阅读更多...
Lock4j简单的支持不同方案的高性能分布式锁实现及源码解析

Lock4j简单的支持不同方案的高性能分布式锁实现及源码解析

文章目录 1.Lock4j是什么?1.1简介1.2项目地址1.3 我之前手写的分布式锁和限流的实现 2.特性3.如何使用3.1引入相关依赖3.2 配置redis或zookeeper3.3 使用方式3.3.1 注解式自动式3.3.2 手动式 4.源码解析4.1项目目录4.2实现思路 5.总结 1.Lock4j是什么? 1.1简介 lock4j是苞米…
阅读更多...
昇思第6天

昇思第6天

函数式自动微分 神经网络的训练主要使用反向传播算法&#xff0c;模型预测值&#xff08;logits&#xff09;与正确标签&#xff08;label&#xff09;送入损失函数&#xff08;loss function&#xff09;获得loss&#xff0c;然后进行反向传播计算&#xff0c;求得梯度&#…
阅读更多...
【算法专题】双指针算法

【算法专题】双指针算法

1. 移动零 题目分析 对于这类数组分块的问题&#xff0c;我们应该首先想到用双指针的思路来进行处理&#xff0c;因为数组可以通过下标进行访问&#xff0c;所以说我们不用真的定义指针&#xff0c;用下标即可。比如本题就要求将数组划分为零区域和非零区域&#xff0c;我们不…
阅读更多...
时序分析基本概念介绍——SI/crosstalk/delta delay/noise/timing Window

时序分析基本概念介绍——SI/crosstalk/delta delay/noise/timing Window

文章目录 前言一、Crosstalk1. Crosstalk Delay Effects2. Crosstalk Noise Effects 二、Crosstalk Analysis1. Crosstalk Delay Analysis2. Crosstalk Noise Analysis 三、如何 fix delta delay 和 noise violations1. 检查delta delay 和 noisedelta delay checknoise check …
阅读更多...
【C语言小知识】缓冲区

【C语言小知识】缓冲区

缓冲区 当我们使用printf()将数据显示在屏幕上&#xff0c;或者使用scanf()函数将数据输入到电脑里&#xff0c;我们是否会产生些许疑问&#xff1f;为何输入的字符会直接显示到屏幕上等等。这里需要介绍一个C语言中的一个关键概念——缓冲区。 当我们使用老式系统进行运行代码…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023