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，一经查实，立即删除！

相关文章

K8S集群应用国产信创适配实战经验总结

K8S集群应用国产信创适配实战经验总结

1.信创适配背景 信创国产化是在当前全球化和科技快速发展的背景下提出的。随着信息技术的快速发展，国内对科技产品和服务的需求日益增长，同时，国际局势的动荡和贸易环境的变化也凸显了自主可控和国产化的重要性。此外，国内政策对数…
阅读更多...
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的神秘面纱，深入细节透彻理解…
阅读更多...
什么是设计模式以及常见的例子（如单例、工厂、观察者等）

什么是设计模式以及常见的例子（如单例、工厂、观察者等）

设计模式（Design Pattern）是一套被反复使用、多数人知晓的、经过分类编目的、代码设计经验的总结。使用设计模式的主要目的是为了可重用代码、让代码更容易被他人理解、提高代码的可靠性。设计模式一般包含模式名称、问题、目的、解决方案、效果等基本要…
阅读更多...
第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.第六关(…
阅读更多...
CSS：选择器 / 14种类型

CSS：选择器 / 14种类型

理解css选择器 CSS选择器是CSS（层叠样式表）中的关键部分，它允许开发者指定哪些HTML元素应该被应用一组特定的样式规则。选择器可以非常具体，只针对一个元素，也可以相当宽泛，影响多个元素。理解CSS选择器对…
阅读更多...
el-table实现固定列，及解决固定列导致部分滚动条无法拖动的问题

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

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

论系统架构

软件架构是动态的。 架构分类 4R架构 Rank&#xff08;顶层架构&#xff0c;架构是怎样分层的&#xff0c;自顶向下展现&#xff09; Role&#xff08;架构包含那些角色&#xff09; Relation&#xff08;角色之间的关系是什么&#xff09; Rule&#xff08;角色之间是如…
阅读更多...
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;…
阅读更多...
Linux 安装 sftp

Linux 安装 sftp

参考资料&#xff1a; linux 安装sftp及使用sftp工具类上传和下载-CSDN博客 安装 OpenSSH 服务&#xff0c;启动 SSH 服务&#xff0c;并设置为开机启动&#xff1a; yum install openssh-server systemctl start sshd systemctl enable sshd 新增用户&#xff08;yk_sftp 为…
阅读更多...
最新文章

Copyright @ 2022~2023