README

版本 2.3.22

适用 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 ...]` ⇒ 联系

`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版本号。

参数定义

所有参数都可以处理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
}

vanderlee / swaggergen

维护者

详细信息

README

简介

安装

使用 SwaggerGen

SwaggerGen 类

__construct($host = '', $basePath = '', $dirs = array())

mixed getSwagger($files, $dirs = array(), $format = self::FORMAT_ARRAY)

define($name, $value = 1)

undefine($name)

创建文档

注释

命令

上下文

预处理器命令

define 名称 [值]

undef 名称

if 名称 [值]

ifdef 名称

ifndef 名称

else

elif 名称 [值]

endif

SwaggerGen上下文和命令

uses 引用

x-[...] 数据

BodyParameter

Contact

email 电子邮件

name 文本 ...

url url

Error

ExternalDocumentation

description 文本 ...

url url

Header

description 文本 ...

信息

contact [url] [email] [name ...] ⇒ 联系

description 文本 ...

license [url] [name ...] ⇒ 许可证

terms text ...

title text ...

version number

许可证

name 文本 ...

url text ...

操作

body/body? definition name [description ...] ⇒ 主体参数

consumes mime1 [mime2 ... mimeN]

已弃用

description 文本 ...

doc url [description ...] ⇒ 外部文档

error statuscode [description] ⇒ 错误

errors statuscode1 [statuscode2 ... statuscodeN]

form/form? definition name [description ...] ⇒ 参数

header/header? definition name [description ...] ⇒ 参数

id name

parameter name

path definition name [description ...] ⇒ 参数

produces mime1 [mime2 ... mimeN]

query/query? 定义名称 [描述 ...] ⇒ 参数

require 安全方案1 [安全方案2 ... 安全方案N]

response 状态码 定义 描述 ⇒ 响应

response 参考 状态码

schemes 方案1 [方案2 ... 方案N]

summary 文本 ...

tags 标签1 [标签2 ... 标签N]

参数

路径

operation 方法 [摘要 ...] ⇒ 操作

description 文本 ...

响应

example 名称 内容

header 类型 名称 [描述] ⇒ 头部

模式

doc url [description ...] ⇒ 外部文档

title text ...

`__construct($host = '', $basePath = '', $dirs = array())`

`mixed getSwagger($files, $dirs = array(), $format = self::FORMAT_ARRAY)`

`define($name, $value = 1)`

`undefine($name)`

`define` `名称 [值]`

`undef` `名称`

`if` `名称 [值]`

`ifdef` `名称`

`ifndef` `名称`

`else`

`elif` `名称 [值]`

`endif`

`uses` `引用`

`x-[...]` `数据`

`email` `电子邮件`

`name` `文本 ...`

`url` `url`

`description` `文本 ...`

`url` `url`

`description` `文本 ...`

`contact` `[url] [email] [name ...]` ⇒ 联系

`description` `文本 ...`

`license` `[url] [name ...]` ⇒ 许可证

`terms` `text ...`

`title` `text ...`

`version` `number`

`name` `文本 ...`

`url` `text ...`

`body`/`body?` `definition name [description ...]` ⇒ 主体参数

`consumes` `mime1 [mime2 ... mimeN]`

`已弃用`

`description` `文本 ...`

`doc` `url [description ...]` ⇒ 外部文档

`error` `statuscode [description]` ⇒ 错误

`errors` `statuscode1 [statuscode2 ... statuscodeN]`

`form`/`form?` `definition name [description ...]` ⇒ 参数

`header`/`header?` `definition name [description ...]` ⇒ 参数

`id` `name`

`parameter` `name`

`path` `definition name [description ...]` ⇒ 参数

`produces` `mime1 [mime2 ... mimeN]`

`query`/`query?` `定义名称 [描述 ...]` ⇒ 参数

`require` `安全方案1 [安全方案2 ... 安全方案N]`

`response` `状态码定义描述` ⇒ 响应

`response` `参考状态码`

`schemes` `方案1 [方案2 ... 方案N]`

`summary` `文本 ...`

`tags` `标签1 [标签2 ... 标签N]`

`operation` `方法 [摘要 ...]` ⇒ 操作

`description` `文本 ...`

`example` `名称内容`

`header` `类型名称 [描述]` ⇒ 头部

`doc` `url [description ...]` ⇒ 外部文档

`title` `text ...`

`description` `描述 ...`

`description` `文本 ...`

`scope` `名称 [描述 ...]`

`consumes` `mime1 [mime2] ... [mimeN]`

`contact` `[url] [email] [name ...]` ⇒ 联系

`definition` `名称` [type] ⇒ 模式

`description` `text ...` ⇒ Info

`doc` `url [description ...]` ⇒ 外部文档

`endpoint` `/path [tag] [description ...]` ⇒ Path

`license` `[url] [name ...]` ⇒ 许可证

`produces` `mime1 [mime2] ... [mimeN]`

`require` `name [scopes]`

`response` `name definition description` ⇒ Response

`schemes` `scheme1 [scheme2] ... [schemeN]`

`security` `name type [params ...]` ⇒ SecurityScheme

`tag` `tag [description ...]` ⇒ Tag

`terms` `text ...` ⇒ 信息

`title` `text ...` ⇒ 信息

`version` `number` ⇒ 信息

`description` `文本 ...`

`doc` `url [description ...]` ⇒ 外部文档