位置：首页-资讯-后端开发

Swagger php注解常用语法梳理

2024-04-02 19:55

短信预约 -IT技能 免费直播动态提醒

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

Swagger 优势

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

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

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

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

1、基础信息

参数

字段名称	类型	描述
version	string	需要 Api版本信息。
title	string	需要 API的标题。
description	string	参数的简要说明。
termsOfService	string	API的服务条款。
contact	联系对象	API的联系信息。
license	许可对象	API的许可证信息。

2、@OA\Contact 联系信息

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

字段名称	类型	描述
url	string	联系人/组织的站点。
name	string	联系人/组织的名称。
email	string	联系人/组织的邮箱。

3、@OA\License 联系信息

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

字段名称	类型	描述
url	string	联系人/组织的站点。
name	string	联系人/组织的名称。
email	string	联系人/组织的邮箱。

二、@OA\Server 服务器新

API 服务器

字段名称	类型	描述
url	string	Api服务器地址，。
description	string	Api服务器描述。
variables	string	联系人/组织的邮箱。

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

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

示例

1、@OA\Parameter 参数说明

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

示例：

2、@OA\Response 参数描述

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