首页 > 编程语言 >Swagger php注解常用语法梳理

Swagger php注解常用语法梳理

时间：2024-07-01 10:58:51浏览次数：19  
标签：php description 接口 API 分组 OA 注解 Swagger type

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="[email protected]",
 *          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="[email protected]",
 *    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 大全

标签：php,description,接口,API,分组,OA,注解,Swagger,type
From： https://blog.csdn.net/nbplus_007/article/details/140094996

相关文章

  • 配置 Swagger + 注释
    打开Xml文件生成，右键项目进入属性设置： 取消未进行注释而进行提示的警告： 然后Program.cs增加代码： 代码：builder.Services.AddSwaggerGen(s=>{//获取xml文件名称varxmlFileName=$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";//包含注释,......
  • PHP转Go系列 | GET 和 POST 请求的使用姿势
    大家好，我是码农先森。说到HTTP请求工具想必对我们做Web开发的程序员都不陌生，只要涉及到网络请求都必须使用。对于我们PHP程序员来说，最熟悉不过的就是CURL扩展，只要安装的这个扩展便可随意发起HTTP请求。但在PHP语言中还有一个很好用的Composer包「guzzlehttp/guzzl......
  • PHP 面向对象编程（OOP）入门指南
    面向对象编程（Object-OrientedProgramming，简称OOP）是一种编程范式，通过使用对象来设计和组织代码。PHP作为一种广泛使用的服务器端脚本语言，支持面向对象编程。本文将介绍PHP面向对象编程的基本概念和用法，并提供示例代码帮助理解。一、面向对象编程的基本概念1.1类和对象......
  • JAVA高级进阶13单元测试、反射、注解
    第十三天、单元测试、反射、注解单元测试介绍单元测试就是针对最小的功能单元(方法)，编写测试代码对其进行正确性测试咱们之前是如何进行单元测试的？有啥问题？只能在main方法编写测试代码，去调用其他方法进行测试。无法实现自动化测试，一个方法测试失败，可能影响其他方......
  • thinkphp3.2.x漏洞分析
    tp3.2.31.开始入口文件就是www/index.php，index.php包含了框架的入口文件，所以访问后可以直接加载thinkphp框架配置文件thinkphp的配置文件在www/ThinkPHP/Conf/convention.phpurl大小写url默认是大小写敏感的，也可以通过修改convertion.php，达到url不区分大小写的目的'URL_C......
  • SSM-学情分析系统-56772（免费领源码+开发文档）可做计算机毕业设计JAVA、PHP、爬虫、APP
    学情分析系统摘 要随着科学技术的飞速发展，各行各业都在努力与现代先进技术接轨，通过科技手段提高自身的优势；对于学情分析系统当然也不能排除在外，随着网络技术的不断成熟，带动了学情分析系统，它彻底改变了过去传统的管理方式，不仅使服务管理难度变低了，还提升了管理的灵活性。这......
  • 基于SpringBoot的高校大学生学科竞赛管理系统+53135（免费领源码）可做计算机毕业设计JAVA
    springboot高校大学生学科竞赛管理系统的设计与实现摘 要随着互联网趋势的到来，各行各业都在考虑利用互联网将自己推广出去，最好方式就是建立自己的互联网系统，并对其进行维护和管理。在现实运用中，应用软件的工作规则和开发步骤，采用Java技术建设高校大学生学科竞赛管理系统。......
  • XAMPP Windows PHP-CGI 代码执行漏洞(CVE-2024-4577) | Goby漏洞预警
    漏洞描述：PHP是一种在服务器端执行的脚本语言,在PHP的8.3.8版本之前存在命令执行漏洞,由于Windows的“Best-FitMapping”特性,在处理查询字符串时,非ASCII字符可能被错误地映射为破折号（-）,导致命令行参数解析错误,当php_cgi运行在Windows平台上，且代码页为繁体中文、简......
  • 基础篇——html与php联动
    基础篇——html与php联动前端包含html(内容)与css(修饰)，后端包含php(处理)和sql(存储)此处通过设计一个简单的登录+注册系统，说明html与php的联动过程(php与sql联动将在下一章阐述)这里采用了混编技术(html代码内嵌php代码)，其基本的交互逻辑为：后端php解析—>前端html渲染—>用......
  • 如何为spring配置全局抛出异常注解
    0.首先了解一个注解@ControllerAdvice，他是spring里的一个注解，用于定义全局逻辑异常、数据绑定、请求处理等逻辑，与@ExceptionHandler等注解使用。ControllerAdvice本质上就是一个Component，他用于对controller实现aop，这里我们就是配合exceptionHandler捕获并抛出异常给前端1.先定......

赞助商

阅读排行

网站主页关于我们联系我们网站地图

本网站内容转载自其他媒体，侵权联系[admin##ips99.com]。

Copyright © 2020-2023 IPS99 版权所有 IPS99