vanderlee / swaggergen
从 PHP 源代码中的简单 PHPdoc-like 注释生成 Swagger/OpenAPI 文档。
Requires
- php: >=7.1.0
- ext-filter: *
- ext-json: *
- ext-mbstring: *
- ext-tokenizer: *
Requires (Dev)
- phpunit/phpunit: ^9.5
Suggests
- ext-yaml: Allows producing Swagger docs in Yaml format
- dev-master
- 2.3.22
- 2.3.21
- 2.3.20
- 2.3.19
- 2.3.18
- 2.3.17
- 2.3.16
- 2.3.15
- 2.3.14
- 2.3.13
- 2.3.12
- 2.3.11
- 2.3.10
- 2.3.9
- 2.3.8
- 2.3.7
- 2.3.6
- 2.3.5
- 2.3.4
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.15
- 2.0.14
- 2.0.13
- 2.0.12
- 2.0.11
- 2.0.10
- 2.0.9
- 2.0.8
- 2.0.7
- 2.0.6
- 2.0.5
- dev-scrutinizer-patch-8
- dev-customtypes
- dev-scrutinizer-patch-7
- dev-scrutinizer-patch-6
- dev-scrutinizer-patch-5
- dev-debug
- dev-scrutinizer-patch-4
- dev-scrutinizer-patch-3
- dev-scrutinizer-patch-2
- dev-scrutinizer-patch-1
This package is auto-updated.
Last update: 2024-09-11 13:00:16 UTC
README
版本 2.3.22
版权 © 2014-2024 Martijn van der Lee Toyls.com.
适用 MIT 开源许可证。
简介
SwaggerGen 是一个 PHP 库,用于从 PHP 源代码生成 Swagger REST API 文档。
它读取以 @rest\
开头的注释,包含描述 API 的命令。使用 SwaggerGen 的目的是对常规 PHP-documentor 风格的文档进行自然扩展。您可以像描述方法一样描述 REST API 调用。
使用几个简单的命令,如 @rest\endpoint /users
和 @rest\method GET 获取所有用户的列表
,即可获得 API 的定义。通过添加 @rest\response 200 array(object(name:string, age:int[0,>, gender:enum(male,female)))
语句,您已经定义了它将返回的确切内容。您也可以仅定义一个 User
并使用 @rest\response 200 array(User)
语句或甚至仅使用 @rest\response ok [User]
。
SwaggerGen 使编写高质量的文档变得快速直观。
使用 Swagger-UI 阅读和测试您的 API,如下例所示,这是使用 SwaggerGen 实时生成的:示例(仅在 PHP 服务器上运行时可用)。
SwaggerGen 与最新的 Swagger 2.0 规范 兼容,这是 Open API Initiative 的基础。
安装
需要 PHP 5.4 或更高版本。如果不需要更新功能,则支持 PHP 5.3。不能保证 SwaggerGen 今后在 PHP 5.3 上继续工作。
使用 Composer 安装
composer require vanderlee/swaggergen
请确保您使用的是 2.x.x 版本或更高版本。
SwaggerGen 旨在与 PSR-4 兼容,因此您应该能够在任何包管理器中使用它。
使用 SwaggerGen
使用 SwaggerGen 生成 Swagger 文档最简单的一部分是设置。
-
设置您的 (PSR-0, PSR-4 或自定义) 自动加载器以使用 SwaggerGen 目录。
如果您还没有自动加载器,可以查看示例文件夹中的自动加载器。
-
创建
/SwaggerGen/SwaggerGen
类的实例。您可以在构造函数中指定服务器的域名和 API 的路径。
-
调用
array SwaggerGen->getSwagger(string[] $filenames)
方法以生成文档。只需提供包含您的 API 操作定义的文件。如果您的 API 使用其他文件,只需在
SwaggerGen
构造函数中指定目录数组,这些文件在需要时将自动解析。 -
您已经完成了。您的文档已生成。剩下的只是输出它。将其存储在文件中或实时返回。
如果您想使用预处理器,您可能需要在步骤 2 之后调用您的 SwaggerGen
实例的 SwaggerGen->define(string $name, string $value)
方法来定义预处理器变量名称。
以下是一个典型的示例
// Assuming you don't already have an autoloader
spl_autoload_register(function ($classname) {
include_once __DIR__ . $classname . '.php';
});
$SwaggerGen = new \SwaggerGen\SwaggerGen(
$_SERVER['HTTP_HOST'],
dirname($_SERVER['REQUEST_URI']),
[__DIR__ . '/api']
);
$SwaggerGen->define('admin'); // admin = 1
$SwaggerGen->define('date', date('Y-m-d')); // date = "2015-12-31"
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
$SwaggerGen->define('windows'); // windows = 1 (only if on Windows OS)
}
$swagger = $SwaggerGen->getSwagger(['Example.php']);
header('Content-type: application/json');
echo json_encode($swagger);
SwaggerGen 类
你需要了解的唯一类是位于同名命名空间 SwaggerGen
下的 SwaggerGen
类。
__construct($host = '', $basePath = '', $dirs = array())
使用给定的 host
和 basePath
创建一个新的 SwaggerGen 对象,并提供一组 dirs
用于扫描可能从您即将扫描的源代码文件中引用的类。
$host
应该是域名,例如www.example.com
。$basePath
应该是 API 根的 URL 路径,例如/api/v1
。
mixed getSwagger($files, $dirs = array(), $format = self::FORMAT_ARRAY)
通过扫描提供的文件列表来生成 Swagger/OpenAPI 文档。您可以指定额外的 dirs
来扫描类文件,并提供一个 format
来指定您想要输出的文档格式。
默认情况下,文档以数组形式输出,准备进行编码为 JSON、YAML 或手动后处理。以下格式是 SwaggerGen
类的常量。
FORMAT_ARRAY
输出原始数组。FORMAT_JSON
JSON 编码输出(MIME 类型application/json
)。FORMAT_JSON_PRETTY
带有人性化布局的 JSON 编码输出(MIME 类型application/json
)。FORMAT_YAML
YAML(UTF-8 字符编码)输出(MIME 类型application/x-yaml
(最常见)或text/yaml
)。
define($name, $value = 1)
定义一个用于预处理器命令的值。默认情况下,其值将被设置为 1
。
undefine($name)
取消定义一个值,使其不再被预处理器命令识别。
创建文档
SwaggerGen 接收多个源文件,并扫描注释以查找它理解的命令。以下是一个 SwaggerGen 理解的注释类型简短示例
/*
* @rest\description SwaggerGen 2 Example API
* @rest\title Example API
* @rest\contact http://example.com Arthur D. Author
* @rest\license MIT
* @rest\security api_key apikey X-Api-Authentication header Authenticate using this fancy header
* @rest\require api_key
*/
注释
所有注释都会被解析,这包括文档注释(/** ... */
)和普通注释,包括单行(// ...
)和多行(/* ... */
)。
附加到函数、方法和类上的注释。任何位于函数、方法或类之前立即的文档注释都将附加到该函数、方法或类。其他注释将附加到包含它们的函数、方法或类。
命令
所有命令都必须以 @rest\
前缀开头,以区分 SwaggerGen 语句和普通注释语句以及其他工具(如 PHP-Documentor)的语句。
默认情况下,所有命令都是多行的;命令之后的任何不以下划线符号(@
)开头的行都将自动附加到上一行的命令。
您可以使用 uses
命令来引用 SwaggerGen 文档中的其他函数、方法或类。此命令允许您指定要包含其文档的其他函数、方法或类。
命令按照它们出现的顺序进行处理。这包括使用 uses
命令引用的任何文档。
上下文
SwaggerGen 使用一组上下文。每个上下文代表将要生成的 Swagger 文档的某个部分。每个上下文支持一些命令,这些命令在该上下文中具有意义。
您最初位于 Swagger 上下文。
您可以使用当前上下文中的某些命令来切换上下文。在此手册中,每当命令切换上下文时,它将在命令语法描述的末尾标记为 '⇒ 上下文名称'。
如果命令在当前上下文中不被识别,则从堆栈中移除上下文,上一个上下文将尝试处理该命令。如果没有上下文能够处理该命令,SwaggerGen 将报告此错误。
预处理器命令
SwaggerGen 具有一组有限的预处理器语句,用于在运行时删除或更改生成的文档的部分。
预处理语句松散地基于C/C++的预处理程序。
通过定义变量名称并检查变量名称是否已定义,或检查变量名称是否有特定的值来进行工作。
SwaggerGen当前没有预定义的变量,但在扫描开始之前,您可以自己定义变量,将它们分配给SwaggerGen解析器。
预处理语句可以嵌套,并适用于PHP和文本。
define
名称 [值]
定义一个变量名称,并可选择为其赋值。
undef
名称
删除变量名称的定义。
if
名称 [值]
如果变量名称已定义,并且(如果提供),其值等于指定的值,则处理所有后续的SwaggerGen命令直到下一个预处理命令。否则,不要处理这些命令。
ifdef
名称
如果变量名称已定义,则处理所有后续的SwaggerGen命令直到下一个预处理命令。否则,不要处理这些命令。
ifndef
名称
如果变量名称未定义,则处理所有后续的SwaggerGen命令直到下一个预处理命令。否则,不要处理这些命令。
else
如果之前的if...
或elif
预处理命令不匹配,则处理所有后续的SwaggerGen命令直到下一个预处理命令。否则,不要处理这些命令。
elif
名称 [值]
如果之前的if...
或elif
预处理命令不匹配,并且如果变量名称已定义,并且(如果提供),其值等于指定的值,则处理所有后续的SwaggerGen命令直到下一个预处理命令。否则,不要处理这些命令。
endif
结束上一个if...
、elif
或else
预处理命令的SwaggerGen命令块。
SwaggerGen上下文和命令
按字母顺序排列以供参考
以下命令可以从任何上下文中使用。
uses
引用
包含对另一个函数、方法或类的引用。
例如
uses functionName
uses self::staticMethodName
uses $this->methodName
uses ClassName::staticMethodName
uses ClassName->methodName
SwaggerGen在self
和this
之间,或在静态和动态::
和->
之间没有区别。这些可以互换使用,不会产生任何影响。尽管建议坚持使用适当的术语。
如果无法在指定的类中找到方法,则使用类继承。
别名:see
x-[...]
数据
将自定义扩展(以x-
开头)添加到当前上下文。
扩展没有任何额外的功能,并被视为原始文本数据块。
BodyParameter
表示一个请求体参数。
有关命令列表,请参阅“参数定义”章节。可用的命令取决于特定类型。
Contact
包含API的联系人信息。
email
电子邮件
设置联系人的电子邮件地址。
name
文本 ...
设置联系人的姓名。
url
url
设置用户可以联系维护者(们)的URL。
Error
表示带有错误状态码的响应。
有关命令,请参阅响应上下文。
ExternalDocumentation
包含对创建此上下文的环境的附加文档的URL引用。
description
文本 ...
设置此外部文档的描述文本。
url
url
设置指向外部文档的URL。
Header
表示响应头。
description
文本 ...
设置此响应头的描述文本。
信息
包含关于API的非技术信息,例如描述、联系方式和免责声明。
contact
[url] [email] [name ...]
⇒ 联系
设置此API的联系人或人员。您可以按任意顺序指定URL、电子邮件地址和姓名。URL和电子邮件地址将自动检测,姓名将包括所有剩余文本(通过空格正确分隔)。
description
文本 ...
Set the description for the API.
license
[url] [name ...]
⇒ 许可证
设置此API的许可证。您可以按任意顺序指定URL和名称。如果您省略了URL,您可以使用任意数量的预定义名称,这些名称将自动扩展为完整的URL,例如 gpl
、gpl-2.1
或 bsd
。
terms
text ...
设置此API的服务条款文本。
别名:tos
、termsofservice
title
text ...
设置API标题。
version
number
设置API版本号。
许可证
表示适用于API的许可证的名称和URL。
name
文本 ...
设置许可证的名称。如果您尚未设置URL,如果它是多个认可的许可证名称之一(如 mpl
或 apache-2
),则可能会自动设置URL。
url
text ...
设置许可证的URL。
操作
描述一个操作;使用特定方法调用特定路径。
body
/body?
definition name [description ...]
⇒ 主体参数
为此操作添加一个新的表单参数。
使用 body
使参数成为必需。使用 body?
(带问号)使参数成为可选。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
consumes
mime1 [mime2 ... mimeN]
添加此操作能够理解的MIME类型。例如:"application/json"、"multipart/form-data" 或 "application/x-www-form-urlencoded"。
已弃用
将此操作标记为已弃用。
description
文本 ...
设置操作的长期描述。
doc
url [description ...]
⇒ 外部文档
设置指向更多文档的URL。
别名:docs
error
statuscode [description]
⇒ 错误
添加此操作可能返回的可能错误状态码,包括可选的描述文本。
如果没有提供描述,将使用状态码的标准原因。
errors
statuscode1 [statuscode2 ... statuscodeN]
添加此操作可能返回的几个可能错误状态码。
form
/form?
definition name [description ...]
⇒ 参数
为此操作添加一个新的表单参数。
使用 form
使参数成为必需。使用 form?
(带问号)使参数成为可选。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
header
/header?
definition name [description ...]
⇒ 参数
为此操作添加一个新的头参数。
使用 header
使参数成为必需。使用 header?
(带问号)使参数成为可选。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
id
name
为此操作设置操作id。
name
ID名称必须在文档中的所有操作中是唯一的。如果您指定了一个已设置的ID,将引发异常。
parameter
name
通过引用全局定义的参数的名称添加一个新的参数。
name
参数引用的全局唯一名称。
别名:param
path
definition name [description ...]
⇒ 参数
为此操作添加一个新的路径参数。
path
参数始终是必需的;它们不能是可选的。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
produces
mime1 [mime2 ... mimeN]
添加此操作能够生成的MIME类型。例如:"application/xml" 或 "application/json"。
query
/query?
定义名称 [描述 ...]
⇒ 参数
为此操作添加一个新的查询参数。
使用 query
使参数成为必需。使用 query?
(带有问号)使参数成为可选。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
require
安全方案1 [安全方案2 ... 安全方案N]
为此操作设置所需的安全方案。
安全方案可以在 Swagger 上下文中定义。
response
状态码 定义 描述
⇒ 响应
添加一个可能的响应状态码以及将要返回的数据定义。尽管对于错误状态码通常使用 error
或 errors
命令,但您也可以使用此命令,包括返回定义。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
response
参考 状态码
参考一个响应定义。
此 reference
名称必须在 Swagger 上下文中定义的响应定义中存在。
请注意,这是 response
命令的两个可能签名之一。
schemes
方案1 [方案2 ... 方案N]
为此操作添加任意数量的方案。
summary
文本 ...
设置操作的简要描述。
tags
标签1 [标签2 ... 标签N]
为此操作添加任意数量的标签。
参数
代表表单、查询、头部或路径参数。
有关命令列表,请参阅“参数定义”章节。可用的命令取决于特定类型。
路径
代表URL端点或路径。
operation
方法 [摘要 ...]
⇒ 操作
向最近指定的端点添加一个新操作。方法可以是 get
、put
、post
、delete
或 patch
中的任何一个。
description
文本 ...
如果存在标签,则设置标签的描述,否则为空。
响应
代表一个响应。
example
名称 内容
向响应添加一个示例。
name
示例的唯一单字(不带空格)名称。每个响应必须是唯一的。
content
内容可以是任何类型。可以是字符串、JSON对象(可选引号)、false
、true
、null
或数字(带或不带小数点)。
header
类型 名称 [描述]
⇒ 头部
向响应添加一个头部。
type
必须是 string
、number
、integer
、boolean
或 array
。
name
必须是有效的HTTP头部名称。例如: X-Rate-Limit-Limit
。
模式
代表类型的定义,例如数组。
doc
url [description ...]
⇒ 外部文档
设置指向更多文档的URL。
别名:docs
title
text ...
设置此模式的标题。
description
描述 ...
设置此模式的描述。
有关其他命令的列表,请参阅 参数定义 章节中的说明。可用的命令取决于特定类型。
安全方案
代表一种将用户/客户端身份验证到服务器的单种方式。您使用Swagger上下文中的 security
命令指定安全方案类型及其设置。
description
文本 ...
设置描述。
scope
名称 [描述 ...]
添加一个带有可选描述的新OAuth2作用域名称。
Swagger
代表整个API文档。这是命令的初始上下文。
consumes
mime1 [mime2] ... [mimeN]
添加API能够理解的MIME类型。例如:"application/json"、"multipart/form-data" 或 "application/x-www-form-urlencoded"。
别名: consume
contact
[url] [email] [name ...]
⇒ 联系
设置此API的联系人或人员。您可以按任意顺序指定URL、电子邮件地址和姓名。URL和电子邮件地址将自动检测,姓名将包括所有剩余文本(通过空格正确分隔)。
definition
名称
[type] ⇒ 模式
使用指定的引用名称开始定义模式。
定义可以作为只读使用感叹号在定义命令的末尾指定。例如,definition! user
将创建一个用户模型,它将出现在 GET 响应中,并在 POST、PUT 和 PATCH 请求中被省略。
当没有指定类型时,definition
创建一个 object
定义。您可以指定 type
以创建其他类型的定义。
definition PositiveInteger integer[1,>
definition ArrayOfString array(string)
请参阅 参数定义 章节以了解所有可能的定义类型的详细描述。
别名:model
(出于历史原因)
description
text ...
⇒ Info
设置 API 的描述。
doc
url [description ...]
⇒ 外部文档
设置指向更多文档的URL。
别名:docs
endpoint
/path [tag] [description ...]
⇒ Path
使用 /path 创建一个端点。如果设置了标签,则该端点将被分配到该名称的标签组。如果设置了描述,则将设置组的描述。
license
[url] [name ...]
⇒ 许可证
设置此 API 的许可。您可以根据需要以任何顺序指定名称中的 URL。如果您省略了 URL,则可以使用任意数量的预定义名称,这些名称将自动扩展到完整的 URL,例如 gpl
、gpl-2.1
、mit
或 bsd
。
produces
mime1 [mime2] ... [mimeN]
添加 API 能够生产的 mime 类型。例如 "application/xml" 或 "application/json"。
别名:produce
require
name [scopes]
设置所需的密钥方案名称。如果给出了多个名称,则它们都必须适用。如果指定了 oath2
方案,则您可以
response
name definition description
⇒ Response
添加一个响应定义,包含返回数据的模式定义。您可以省略 definition
,通过指定 null
代替。
参见 参数定义 章节以获取所有可能定义格式的详细描述。
schemes
scheme1 [scheme2] ... [schemeN]
添加协议方案。例如 "http" 或 "https"。
别名:scheme
security
name type [params ...]
⇒ SecurityScheme
定义一个可用于 API 和单个操作的密钥方法。名称可以是您选择的任何随机名称。这些名称将在稍后用于引用安全方案。
类型
必须是 basic
、apikey
或 oauth2
。参数取决于类型。
对于 basic
,您只能指定描述文本。
对于 apikey
,您必须首先指定用于查询参数或头部的名称,然后使用 query
或 header
设置 apikey 的类型。可选地跟一个描述文本。
对于 oauth2
,您必须设置流程类型 implicit
、password
、application
或 accesscode
。对于 accesscode
类型,您必须指定两个 URL,分别用于授权和令牌,对于其他类型只需要一个 URL。可选地跟一个描述文本。您可能需要使用 scope
命令添加范围。
security
name
basic
[description ...]
security
name
apikey
header-name
header
[description ...]
security
name
apikey
query-variable
query
[description ...]
security
name
oauth2 implicit
auth-url [description ...]
security
name
oauth2 password
token-url [description ...]
security
name
oauth2 application
token-url [description ...]
security
name
oauth2 accesscode
auth-url token-url [description ...]
tag
tag [description ...]
⇒ Tag
指定标签定义;本质上是将端点路径分组在一起的分类。
别名:api
(历史原因)。
terms
text ...
⇒ 信息
设置此API的服务条款文本。
别名:tos
、termsofservice
title
text ...
⇒ 信息
设置API标题。
version
number
⇒ 信息
设置API版本号。
标签
标签用于将路径和操作分组到逻辑分类中。
description
文本 ...
设置描述。
doc
url [description ...]
⇒ 外部文档
设置指向更多文档的URL。
别名:docs
参数定义
所有参数都可以处理example
命令
命令
example
内容 设置任何类型的示例内容。可以是字符串、JSON对象(可选引号)、false
、true
、null
或数字(带或不带小数点)。
string, byte, binary, password
表示文本。
type(pattern)[0,>=default
- 类型:
string
或binary
, - 范围:[min,max]。使用
[
或]
表示包含,使用<
或>
表示不包含。空min
值表示零。空max
值表示无穷大。 - 默认值:任何不包含空白的有效文本。
命令
default
值 设置默认值。enum
value1 value2 ... valueN 设置或添加允许的值。
示例
string
一个简单的文本字段。string(^[a-z]{2}-[A-Z]{2}$)
匹配 ISO "ll-CC" 位置的字符串。string[,256>=red
最多 255 个字符的文本,默认为 "red"。binary[1,8]
最多 8 个二进制位,至少一个。
int32(整数,int),int64(长整型)
表示没有小数的数字。
type[0,>=default
- 类型:
integer
、int
、int32
、long
或int64
。 - 范围:[min,max]。使用
[
或]
表示包含,使用<
或>
表示不包含。空min
或max
值表示无穷大。 - 默认值:任何有效的整数。
命令
default
值 设置默认值。enum
value1 value2 ... valueN 设置或添加允许的值。step
值 设置数字之间的步长。
示例
int
没有默认值或范围限制的 32 位整数。long<,0>
只有 64 位负整数。integer[0,>=100
32 位正整数或零,默认为 100。
float, double
表示带小数的浮点数。
type[0,>=default
- 类型:
float
或double
- 范围:[min,max]。使用
[
或]
表示包含,使用<
或>
表示不包含。空min
或max
值表示无穷大。 - 默认值:任何有效的整数。
命令
default
值 设置默认值。enum
value1 value2 ... valueN 设置或添加允许的值。step
值 设置数字之间的步长。
示例
float
没有默认值或范围限制的 32 位浮点数。double<,1>
64 位浮点数,最大值为 1(但不包括 1)。float<0,>=0.1
32 位正数,不包括 0,默认为 0.1。
boolean (bool)
一个真/假选择。
type=default
- 类型:
boolean
或bool
。 - 默认值:
true
、false
、1(真)或 0(假)。
命令
default
值 设置默认值。
示例
boolean
一个基本的布尔值。bool=true
一个布尔值,默认为真。
date, date-time (datetime)
仅限于日期的特殊字符串类型
type=default
- 类型:
date
、date-time
或datetime
。 - 默认值:任何由 PHP DateTime 对象 识别的有效日期格式。
命令
default
日期 设置默认值。
示例
date
一个简单的日期。datetime=2015-12-31T12:34:56Z
日期和时间设置为默认值,没有时区偏移。datetime=2015-12-31T12:34:56.001+01:00
日期和时间设置为默认值,带有分数秒和时区偏移。
csv (array), ssv, tsv, pipes, multi
项目列表
type(definition)[0,>
用于array
列表的替代简写表示法
[definition][0,>
- 类型:
csv
、array
、ssv
、tsv
、pipes
或multi
。 - 范围:[min,max]。使用
[
或]
表示包含,使用<
或>
表示不包含。空min
值表示零。空max
值表示无穷大。 - 默认值:任何不包含空白的有效文本。
- 定义:列表中项目的类型定义。可以将列表定义为项目,创建多维数组。
命令
min
值 设置所需的最小项目数。max
最大值 设置允许的最大项目数。items
定义 设置此列表中项目的定义。
类型
csv
以逗号(,
)分隔。例如:red,green,blue
。别名:array
。ssv
以空格( )分隔。例如:red green blue
。tsv
以制表符分隔。例如:red green blue
。pipes
以管道(|
)分隔。例如:red|green|blue
。multi
查询字符串格式。例如:color=red&color=green&color=blue
。此选项仅适用于form
和query
参数。
示例
csv(string)
一系列以逗号分隔的字符串。
文件
一个文件。
file
无法进一步定义。没有命令。
示例
file
一个文件。
对象
具有属性的对象。通常用作键值映射
object(definition)[0,>
替代简写符号
{definition}[0,>
- 类型:
object
。 - 范围:[min,max]。使用
[
或]
表示包含,使用<
或>
表示排除。空min
值表示没有属性(没有最小值)。空max
值表示无限属性(没有最大值)。 - 定义:以
key:definition
形式的属性定义列表,其中key
可以是任何除:
或?
或!
之外的字符序列。其中?
表示键是可选的。其中!
表示键是只读的。只读意味着可选。
命令
min
值 设置所需的最小项目数。max
最大值 设置允许的最大项目数。property
定义名称 添加一个必需属性。property?
定义名称 添加一个可选属性。property!
定义名称 添加一个只读属性。discriminator
属性名称 将属性设置为区分符。该属性必须是必需的(不能是只读或可选的),但您可以稍后定义它。
示例
object(age:int[18,25>)
包含单个键age
的对象,其整数值大于或等于 18 且小于 25。object(age:int,name?:string[2,>)
包含一个age
和一个可选的name
字符串的对象,其中该值至少有两个字符长。object()[4,8]
包含四个到八个未知属性的对象。
allof
交集类型(数据必须满足所有基类型)。可用于类型组合或实现继承(与 discriminator
结合使用)。也可以用于细化基类型施加的约束。
allof(definition)
- 定义:以逗号分隔的基类型列表,可以是内联定义或对另一个定义的引用
命令
item
类型 将类型添加到所有Of类型列表中
示例
allOf(DataModel,IdModel)
类型组合:实际上创建 DataWithId 类型。allOf(ModelWithOptionalName,object(name:string))
类型细化:实际上使name
属性成为必需。
枚举
一种特殊的字符串类型,其值限于预定义值之一。
enum(value1,value1,...,valueN)=default
- 值:任何不包含空格或逗号的文本。
- 默认值:指定的任何文本。
命令
参见字符串。
示例
enum(red,green,blue)=red
包含 "red"、"green" 或 "blue" 的字符串,默认为 "red"。
uuid
一种特殊的字符串类型,它接受符合 RFC 4122 的通用唯一标识符(UUID)字符串。默认值经过验证以确保仅指定有效的 UUID。
uuid=default
- 默认值:指定的任何文本。
命令
参见字符串。
示例
uuid=123e4567-e89b-12d3-a456-426655440000
一个 uuid 字符串,默认为 uuid "123e4567-e89b-12d3-a456-426655440000"。
refobject
对全局定义的 definition
(即 model
)对象的引用。
refobject(definitionName)
或
definitionName
- 定义名称:全局定义的
definition
的名称。
示例
refobject(Address)
引用名为Address
的全局定义模型。Address
引用名为Address
的全局定义模型。
备注
通常,仅使用定义名称就足够了。如果您使用的名称也是作为内置参数类型使用的,例如string
或object
,请使用refobject(...)
。最好将所有定义名称的首字母大写(即Address
)。如果您不使用首字母大写(即address
),使用refobject(...)
也提供了最安全的向前兼容策略。
附录
.mime类型
某些命令,如consumes
和produces
,将mime类型作为参数。您可以使用以下预定义的缩写(不区分大小写)来指定完整的mime类型:
fileform multipart/form-data
form application/x-www-form-urlencoded
json application/json
text text/plain
utf8 text/plain; charset=utf-8
yml application/x-yaml
yaml application/x-yaml
php text/x-php
xml text/xml
许可证
有一系列缩写可供使用许可证。如果您想添加其他许可证,请提交一个问题或创建一个pull request。您要编辑的文件是/SwaggerGen/Swagger/License.php
。
以下是当前可用的许可证缩写:
artistic-1.0 https://open-source.org.cn/licenses/artistic-license-1.0
artistic-1 https://open-source.org.cn/licenses/artistic-license-1.0
artistic-2.0 https://open-source.org.cn/licenses/artistic-license-2.0
artistic-2 https://open-source.org.cn/licenses/artistic-license-2.0
artistic https://open-source.org.cn/licenses/artistic-license-2.0
bsd-new https://open-source.org.cn/licenses/BSD-3-Clause
bsd-3 https://open-source.org.cn/licenses/BSD-3-Clause
bsd-2 https://open-source.org.cn/licenses/BSD-2-Clause
bsd https://open-source.org.cn/licenses/BSD-2-Clause
epl-1.0 http://www.eclipse.org/legal/epl-v10.html
epl-1 http://www.eclipse.org/legal/epl-v10.html
epl http://www.eclipse.org/legal/epl-v10.html
apache-2.0 https://apache.ac.cn/licenses/LICENSE-2.0.html
apache-2 https://apache.ac.cn/licenses/LICENSE-2.0.html
apache https://apache.ac.cn/licenses/LICENSE-2.0.html
gpl-1.0 https://gnu.ac.cn/licenses/gpl-1.0.html
gpl-1 https://gnu.ac.cn/licenses/gpl-1.0.html
gpl-2.0 https://gnu.ac.cn/licenses/gpl-2.0.html
gpl-2 https://gnu.ac.cn/licenses/gpl-2.0.html
gpl-3.0 https://gnu.ac.cn/licenses/gpl-3.0.html
gpl-3 https://gnu.ac.cn/licenses/gpl-3.0.html
gpl https://gnu.ac.cn/licenses/gpl-3.0.html
lgpl-2.0 https://gnu.ac.cn/licenses/lgpl-2.0.html
lgpl-2.1 https://gnu.ac.cn/licenses/lgpl-2.1.html
lgpl-2 https://gnu.ac.cn/licenses/lgpl-2.1.html
lgpl-3.0 https://gnu.ac.cn/licenses/lgpl-3.0.html
lgpl-3 https://gnu.ac.cn/licenses/lgpl-3.0.html
lgpl https://gnu.ac.cn/licenses/lgpl-3.0.html
mit https://open-source.org.cn/licenses/MIT
mpl-1.1 https://www.mozilla.org/en-US/MPL/1.1/
mpl-1 https://www.mozilla.org/en-US/MPL/1.1/
mpl-2.0 https://www.mozilla.org/en-US/MPL/
mpl-2 https://www.mozilla.org/en-US/MPL/
mpl https://www.mozilla.org/en-US/MPL/
mspl https://msdn.microsoft.com/en-us/library/ff648068.aspx
示例
要查看使用SwaggerGen生成的Swagger文档的示例,请访问示例API文档。
以下是从该示例代码片段:
/**
* @rest\endpoint /user/{username}
* @rest\method GET Get a list of all users
* @rest\path String username Name of the user
* @rest\see self::request
*/
private function getUser($name)
{
/*
* @rest\model User
* @rest\property int age Age of the user in years
* @rest\property int height Height of the user in centimeters
*/
return $this->data['users'][$name]; // @rest\response OK object(age:int[0,100>,height:float) User
}