Swagger php注解常用语法梳理

news2024/11/20 8:33:47

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.coloradmin.cn/o/1881797.html

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

相关文章

CSS 背景添加白色小圆点样式

CSS 背景添加白色小圆点样式

css也是开发过程中不可忽视的技巧 此专栏用来纪录不常见优化页面样式的css代码 效果图: 未添加之前: 代码: background: radial-gradient(circle at 1px 1px, #3d3c3c 2px, transparent 0);background-size: 20px 25px;
阅读更多...
Java代码生成器（开源版本）

Java代码生成器（开源版本）

一、在线地址 Java在线代码生成器：在线访问 二、页面截图 三、核心功能 支持Mybatis、MybatisPlus、Jpa代码生成使用 antlr4 解析SQL语句，保证了SQL解析的成功率支持自定义包名、作者名信息支持自定义方法名、接口地址支持自定义选择是否生成某个方法…
阅读更多...
沃尔玛自养号测评：从入门到精通的全方位指南

沃尔玛自养号测评：从入门到精通的全方位指南

沃尔玛测评自养号优势要点及IP环境搭建技术及主要可以归结为以下几个方面： 一、沃尔玛IP环境搭建技术 1.使用国外的服务器：为了确保测评活动的隐蔽性和安全性，卖家需要选择使用国外的服务器，并通过远程搭建一个安全终端防火墙。…
阅读更多...
IDEA中Java源文件编译后class文件中文乱码

IDEA中Java源文件编译后class文件中文乱码

文章目录 一、设置 一、设置 路径：File -> Settings -> Bulid, Execution,Deployment -> Compiler -> Java Compiler
阅读更多...
2024年度潍坊市职业技能大赛——网络搭建（网络与信息安全管理员）职业技能竞赛样题

2024年度潍坊市职业技能大赛——网络搭建（网络与信息安全管理员）职业技能竞赛样题

2024年度潍坊市职业技能大赛 ——网络搭建（网络与信息安全管理员）职业技能竞赛样题 网络搭建职业技能竞赛组委会 2024年6月 一、项目简介 （一）竞赛须知 1.技能操作比赛时间150分钟，你需要合理分配时间。 2.如果没…
阅读更多...
为什么越来越多的企业选择外包？赋能企业未来

为什么越来越多的企业选择外包？赋能企业未来

软件开发过程包括设计需求、设计方案、产品研发、产品交付、后期维护，许多企业并沒有软件开发的专业能力与工作经验，将软件开发工作进行外包是比较节约成本的，企业能少走不少弯路。 YesPMP平台（一站式软件外包、项目外包服务-YesP…
阅读更多...
自适应站长跑路单页网站源码

自适应站长跑路单页网站源码

跑路单页HTML源码自行修改文字就行了,上传到服务器里面运行即可，本地运行的话音乐会加载不出来，涉及到跨域问题 自适应站长跑路单页网站源码
阅读更多...
ssm校园二手交易平台小程序

ssm校园二手交易平台小程序

设计技术： 开发语言：Java数据库：MySQL技术：SpringMybatisSpringMvc微信小程序 工具：IDEA、Maven、Navicat 主要功能： (a) 管理员；管理员进入系统主要功能包括首页，个人中心&…
阅读更多...
ollama+Dify大模型本地化部署打造个人知识库 (2)

ollama+Dify大模型本地化部署打造个人知识库 (2)

ollama大模型部署-CSDN博客文章浏览阅读26次。Ollama 是一个能在本地机器上轻松构建和运行大型语言模型的轻量级、可扩展框架，适用于多种场景，具有易于使用、资源占用少、可扩展性强等特点。https://blog.csdn.net/weixin_72819498/article/details/1400…
阅读更多...
SAP ABAP 常用的参数

SAP ABAP 常用的参数

目录 一，创建一个单一的输入域：PARAMETERS 二，必输：OBLIGATORY 三，初始值：DEFAULT 四，按钮：复选框 checkbox 五，单选框 RADIOBUTTON GROUP 六，多值的选…
阅读更多...
Oracle连接mysql

Oracle连接mysql

oracle使用的11g，在一台windows服务器；mysql使用的是5.7版本，在另一台windows服务器，这两个服务器之间的网络是互通的。做BI时，要获取不同数据源的数据，这些数据源可能是Oracle，也可能是sqlserv…
阅读更多...
Veno File Manager（VFM）v4.2.7 中文包整理

Veno File Manager（VFM）v4.2.7 中文包整理

Veno File Manager（VFM）是一个简单灵活的即插即用文件管理器，易于使用且具有许多选项。将文件发送给您的客户，使用专用文件夹创建新用户，或仅用作您的个人文件云。从任何设备访问，用户管理和从直观的管理面…
阅读更多...
基于flask的闪现、g对象、蓝图

基于flask的闪现、g对象、蓝图

【 一 】闪现（flash） # 1 flask中得闪现存放数据的地方，一旦取了，数据就没了-实现跨请求间传递数据 # 2 django中有没有类似的东西？message 消息框架# 3 基本使用1 设置：flash(欢迎你、欢迎来到澳门赌场&a…
阅读更多...
LCD 显示--lvds

LCD 显示--lvds

作者简介： 一个平凡而乐于分享的小比特，中南民族大学通信工程专业研究生在读，研究方向无线联邦学习 擅长领域：驱动开发，嵌入式软件开发，BSP开发 作者主页：一个平凡而乐于分享的小比特的个人主页…
阅读更多...
本地Navicat/客户端连接阿里云RDSMySQL时遇到过的问题及解决

本地Navicat/客户端连接阿里云RDSMySQL时遇到过的问题及解决

1.之前开发的RDS MySQL版本和本地MySQL版本最好接近，比如8.0.28和8.0.20好像都是可以兼容的，他们里面都有那个utf8的字符编码，但是后面我选的RDS MySQL版本有点新，是8.0.30甚至更新的版本，之前用C#语言写的连接MySQL以…
阅读更多...
Avalonia 常用控件三 Window窗体相关二

Avalonia 常用控件三 Window窗体相关二

1、效果演示 2、在Views中创建WindowDemo.axaml如下图 WindowDemo.axaml代码如下 <Window xmlns"https://github.com/avaloniaui"xmlns:x"http://schemas.microsoft.com/winfx/2006/xaml"xmlns:d"http://schemas.microsoft.com/expression/blend/…
阅读更多...
【C++题解】1228. 排队打水问题

【C++题解】1228. 排队打水问题

问题&#xff1a;1228. 排队打水问题 类型&#xff1a;贪心 题目描述&#xff1a; 有 n 个人排队到r 个水龙头去打水&#xff0c;他们装满水桶的时间 t1​,t2​,…,tn​ 为整数且各不相等&#xff0c;应如何安排他们的打水顺序才能使他们花费的总时间最少&#xff1f; 每个人…
阅读更多...
嵌入式UI开发-lvgl+wsl2+vscode系列：8、控件（Widgets）（一）

嵌入式UI开发-lvgl+wsl2+vscode系列：8、控件（Widgets）（一）

一、前言 这里将介绍一系列控件&#xff0c;了解后就可以开始基础的开发了。 二、示例 1、Base Obj&#xff08;基础对象&#xff09; 1.1、示例1 #include "../../lv_examples.h" #if LV_BUILD_EXAMPLESvoid lv_example_obj_1(void) {lv_obj_t * obj1;obj1 lv…
阅读更多...
Swift 新结构化并发中鲜为人知的 isolated 参数

Swift 新结构化并发中鲜为人知的 isolated 参数

概述 伴随着 Swift 5.5&#xff08;WWDC21&#xff09;推出的新结构化并发到今年的 WWDC 24 已经有 3 个多年头了。想必大家都对其中 async/awiat、async let、TaskGroup、Actor 等各种概念都了然于胸了吧&#xff1f; 不过小伙伴们可能不知道的是&#xff1a;新结构化并发&a…
阅读更多...
零基础STM32单片机编程入门(五)FreeRTOS实时操作系统详解及实战含源码视频

零基础STM32单片机编程入门(五)FreeRTOS实时操作系统详解及实战含源码视频

文章目录 一.概要二.什么是实时操作系统三.FreeRTOS的特性四.FreeRTOS的任务详解1.任务函数定义2.任务的创建3.任务的调度原理 五.CubeMX配置一个FreeRTOS例程1.硬件准备2.创建工程3.调试FreeRTOS任务调度 六.CubeMX工程源代码下载七.讲解视频链接地址八.小结 一.概要 FreeRTO…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023