README

版本 2.3.21

适用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 perfectpanel/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
 */

注释

所有注释都会被解析，包括文档注释（/** ... */）和普通注释，包括单行注释（// ...）和多行注释（/* ... */）。

附加到函数、方法和类上的注释。任何紧接在函数、方法或类之前的文档注释都会附加到该函数、方法或类。其他注释将附加到包含它们的函数、方法或类。例如，函数内的 SwaggerGen 注释将附加到该函数。

命令

所有命令都必须以前缀 @rest\ 开头，以区分 SwaggerGen 语句和普通注释语句以及来自其他工具（如 PHP-Documentor）的语句。

默认情况下，所有命令都是多行的；任何不以反引号（@）开头的命令行都将自动附加到上一行的命令。

您可以使用 uses 命令来引用 SwaggerGen 文档中的其他函数、方法或类。此命令允许您指定要包含其文档的其他函数、方法或类。

命令按出现的顺序处理。这包括使用 uses 命令引用的任何文档。

上下文

SwaggerGen 使用一个上下文堆栈。每个上下文代表将要生成的 Swagger 文档的某个部分。每个上下文支持一些在上下文中具有意义的命令。

您最初从 Swagger 上下文开始。

您可以使用当前上下文中的某些命令来切换上下文。在此手册中，每当命令切换上下文时，都会在命令语法描述的末尾使用 '⇒ 上下文名称' 标记。

如果在当前上下文中未识别到命令，则将从堆栈顶部删除该上下文，然后尝试由之前的上下文处理该命令。如果没有上下文能够处理该命令，SwaggerGen将报告此错误。

预处理器命令

SwaggerGen在运行时具有一组有限的预处理器语句，用于删除或更改生成的文档的部分。

预处理器语句大致基于C/C++预处理器。

通过为变量名称定义值、检查变量名称是否已定义或检查变量名称是否具有特定值来执行工作。

SwaggerGen目前没有预定义的变量，但您可以在扫描开始之前通过将它们分配给SwaggerGen解析器来自定义变量。

预处理器语句可以嵌套，并且适用于PHP和文本。

`define` `name [value]`

定义一个变量名称，并可选择为其赋值。

`undef` `name`

删除变量名称的定义。

`if` `name [value]`

如果变量名称已定义并且（如果提供），它的值等于指定的值，则处理所有后续的SwaggerGen命令，直到下一个预处理器命令。否则，不处理这些命令。

`ifdef` `name`

如果变量名称已定义，则处理所有后续的SwaggerGen命令，直到下一个预处理器命令。否则，不处理这些命令。

`ifndef` `name`

如果变量名称未定义，则处理所有后续的SwaggerGen命令，直到下一个预处理器命令。否则，不处理这些命令。

`else`

如果之前的if...或elif预处理器命令未匹配，则处理所有后续的SwaggerGen命令，直到下一个预处理器命令。否则，不处理这些命令。

`elif` `name [value]`

如果之前的if...或elif预处理器命令未匹配并且如果变量名称已定义并且（如果提供），它的值等于指定的值，则处理所有后续的SwaggerGen命令，直到下一个预处理器命令。否则，不处理这些命令。

`endif`

结束之前的if...、elif或else预处理器命令的SwaggerGen命令块。

SwaggerGen上下文和命令

按字母顺序排序以供参考

以下命令可以在任何上下文中使用。

`uses` `reference`

包含对另一个函数、方法或类的引用。

例如

uses functionName
uses self::staticMethodName
uses $this->methodName
uses ClassName::staticMethodName
uses ClassName->methodName

SwaggerGen在self和this或静态和动态::和->之间没有区别。这些可以互换而不影响任何内容。尽管建议坚持使用正确的术语。

如果无法在指定的类中找到方法，则使用类继承。

alias: see

`x-[...]` `data`

将自定义扩展（以x-开头）添加到当前上下文。

扩展没有其他功能，被视为原始文本数据块。

BodyParameter

表示一个体参数。

有关命令列表，请参阅《参数定义》章节。可用的命令取决于特定类型。

Contact

包含API的联系方式。

`email` `email`

设置联系人的电子邮件地址。

`name` `text ...`

设置联系人的姓名。

`url` `email`

设置用户可以联系维护者（们）的URL。

错误

表示一个错误状态码的响应。

有关命令，请参阅响应上下文。

外部文档

包含指向创建此上下文的环境的附加文档的URL引用。

`description` `text ...`

设置此外部文档的描述文本。

`url` `url`

设置外部文档的URL。

头部

表示响应头部。

`description` `text ...`

设置此响应头部的描述文本。

信息

包含有关API的非技术信息，例如描述、联系细节和法律小字。

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

设置此API的联系方式或-人员。您可以按任何顺序指定URL、电子邮件地址和名称。URL和电子邮件地址将自动检测，名称将包含所有剩余文本（适当用空格分隔）。

`description` `text ...`

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` `text ...`

设置许可证的名称。如果您尚未设置URL，如果它是以下一系列已识别的许可证名称之一，则可能会自动设置URL，例如mpl或apache-2。

`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` `text ...`

设置操作的详细描述。

`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` `定义名称 [描述 ...]` ⇒ 参数

向此操作添加新的路径参数。

path 参数总是必需的；它们不能是可选的。

有关所有可能定义格式的详细描述，请参阅参数定义章节。

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

添加此操作可以生成的mime类型。例如：“application/xml”或“application/json”。

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

向此操作添加新的查询参数。

使用query使参数必需。使用query?（带有问号）使参数可选。

有关所有可能定义格式的详细描述，请参阅参数定义章节。

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

为此操作设置所需的安全方案。

安全方案可以在Swagger上下文中定义。

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

添加可能的响应状态码以及将返回的数据定义。尽管对于错误状态码通常使用error或errors命令，但您也可以使用此命令以及返回定义来处理这些状态码。

有关所有可能定义格式的详细描述，请参阅参数定义章节。

`response` `引用状态码`

引用响应定义。

引用名称必须存在于Swagger上下文中定义的响应定义中。

请注意，这是response命令可能的两种签名之一。

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

向操作添加任意数量的方案。

`summary` `文本 ...`

设置操作的简要描述。

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

向操作添加任意数量的标签。

参数

表示表单、查询、路径参数的头部。

有关命令列表，请参阅《参数定义》章节。可用的命令取决于特定类型。

路径

表示URL端点或路径。

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

向最近指定的端点添加新的操作。方法可以是get、put、post、delete或patch中的任何一个。

`description` `text ...`

如果存在标签，则设置标签的描述，否则为空。

响应

表示响应。

`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` `描述 ...`

设置此模式的描述。

有关其他命令的列表，请参阅参数定义章节。可用的命令取决于特定类型。

SecurityScheme

表示用户/客户端向服务器进行身份验证的单种方式。您使用Swagger上下文中的security命令指定安全方案的类型及其设置。

`description` `text ...`

设置描述。

`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` `name` [type] ⇒ Schema

使用指定的引用名称开始Schema的定义。

定义可以用感叹号在定义命令的末尾指定为只读。例如：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

添加一个带有数据返回的Schema定义的响应定义。您可以省略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 ...]` ⇒ 标签

指定标签定义；本质上是一个端点路径将被分组在一起的类别。

别名： api（历史原因）。

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

设置此API服务条款的文本。

别名: tos、termsofservice

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

设置API标题。

`version` `number` ⇒ 信息

设置API版本号。

参数定义

所有参数都可以处理 example 命令

命令

example 内容 设置任何类型的示例内容。可以是字符串、JSON对象（可选引号）、false、true、null 或数字（带或不带小数）。

字符串、字节、二进制、密码

表示文本。

type(pattern)[0,>=default

类型： string 或 binary,
范围：[最小值，最大值]。使用 [ 或 ] 表示包含，使用 < 或 > 表示排除。空的 min 值表示零。空的 max 值表示无穷大。
默认值：任何不包含空白的有效文本。

命令

default 值 设置默认值。
enum 值1 值2 ... 值N 设置或添加允许的值。

示例

string 一个简单的文本字段。
string(^[a-z]{2}-[A-Z]{2}$) 匹配 ISO "ll-CC" 语言的字符串。
string[,256>=red 最多 255 个字符的文本，默认为 "red"。
binary[1,8] 最多 8 个二进制位，至少需要 1 个。

int32（整数，int）、int64（长整数）

表示没有小数的数字。

type[0,>=default

类型： integer、int、int32、long 或 int64。
范围：[最小值，最大值]。使用 [ 或 ] 表示包含，使用 < 或 > 表示排除。空的 min 或 max 值表示无穷大。
默认值：任何有效的整数。

命令

default 值 设置默认值。
enum 值1 值2 ... 值N 设置或添加允许的值。
step 值 设置数字之间的步长。

示例

int 没有默认值或限制范围的 32 位整数。
long<,0> 只包含 64 位负整数的。
integer[0,>=100 32 位正整数或零，默认为 100。

float、double

表示带小数的浮点数。

type[0,>=default

类型： float 或 double
范围：[最小值，最大值]。使用 [ 或 ] 表示包含，使用 < 或 > 表示排除。空的 min 或 max 值表示无穷大。
默认值：任何有效的整数。

命令

default 值 设置默认值。
enum 值1 值2 ... 值N 设置或添加允许的值。
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（true）或 0（false）。

命令

default 值 设置默认值。

示例

boolean 基本布尔值。
bool=true 布尔值，默认为 true。

日期、日期时间（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（数组）、ssv、tsv、管道、多

项目列表

type(definition)[0,>

array 列表的替代简写表示法

[definition][0,>

类型： csv、array、ssv、tsv、pipes 或 multi。
范围：[最小值，最大值]。使用 [ 或 ] 表示包含，使用 < 或 > 表示排除。空的 min 值表示零。空的 max 值表示无穷大。
默认值：任何不包含空白的有效文本。
定义：列表中项目类型的定义。可以定义列表作为项目，创建多维数组。

命令

min value 设置所需项目数量的最小值。
max value 设置允许的项目数量的最大值。
items definition 设置此列表中项目的定义。

类型

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

无法进行进一步的定义。没有命令。

示例

file 一个文件。

object

具有属性的对象。通常用作键值映射。

object(definition)[0,>

替代简写符号

{definition}[0,>

type: object。
范围: [min,max]。使用 [ 或 ] 表示包含，使用 < 或 > 表示排除。空的 min 值表示零个属性（没有最小值）。空的 max 值表示无限个属性（没有最大值）。
definition: 以 key:definition 形式，逗号分隔的属性定义列表，其中 key 可以是任何除 : 或 ? 或 ! 之外的字符序列。其中 ? 表示键是可选的。其中 ! 表示键是只读的。只读也意味着可选。

命令

min value 设置所需项目数量的最小值。
max value 设置允许的项目数量的最大值。
property definition name 添加一个必需属性。
property? definition name 添加一个可选属性。
property! definition name 添加一个只读属性。
discriminator propertyName 将属性设置为判别器。该属性必须是必需的（不能是只读或可选的），但您可以稍后定义它。

示例

object(age:int[18,25>) 包含单个键 age 的对象，其整数值大于或等于 18 且小于 25。
object(age:int,name?:string[2,>) 包含 age 和可选 name 字符串的对象，其中值至少为两个字符长。
object()[4,8] 包含四个到八个未知属性的对象。

allof

交集类型（数据必须满足所有基类型）。可用于类型组合或实现继承（与 discriminator 一起使用）。还可以用于细化基类型施加的约束。

allof(definition)

definition: 以逗号分隔的基类型列表，可以是内联定义或对另一个定义的引用

命令

item type 将类型添加到所有Of类型列表中

示例

allOf(DataModel,IdModel) 类型组合：实际上创建了 DataWithId 类型。
allOf(ModelWithOptionalName,object(name:string)) 类型细化：实际上使 name 属性成为必需的。

enum

一种特殊的字符串类型，其值限制为几个预定义值之一。

enum(value1,value1,...,valueN)=default

values: 不包含空白或逗号的任何文本。
default: 所指定文本之一。

命令

参见字符串。

示例

enum(red,green,blue)=red 包含 "red"、"green" 或 "blue" 的字符串，默认为 "red"。

uuid

一种特殊的字符串类型，接受符合 RFC 4122 的通用唯一识别符（UUID）字符串。默认值经过验证以确保仅指定有效的 UUID。

uuid=default

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 类型，而不是指定完整的 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
}

perfectpanel / 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 name [value]

undef name

if name [value]

ifdef name

ifndef name

else

elif name [value]

endif

SwaggerGen上下文和命令

uses reference

x-[...] data

BodyParameter

Contact

email email

name text ...

url email

错误

外部文档

description text ...

url url

头部

description text ...

信息

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

description text ...

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

terms text ...

title text ...

version number

许可证

name text ...

url text ...

操作

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

consumes mime1 [mime2 ... mimeN]

已弃用

description text ...

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 定义名称 [描述 ...] ⇒ 参数

produces mime1 [mime2 ... mimeN]

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

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

response 状态码 定义 描述 ⇒ 响应

response 引用 状态码

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

summary 文本 ...

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

参数

路径

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

description text ...

响应

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` `name [value]`

`undef` `name`

`if` `name [value]`

`ifdef` `name`

`ifndef` `name`

`else`

`elif` `name [value]`

`endif`

`uses` `reference`

`x-[...]` `data`

`email` `email`

`name` `text ...`

`url` `email`

`description` `text ...`

`url` `url`

`description` `text ...`

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

`description` `text ...`

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

`terms` `text ...`

`title` `text ...`

`version` `number`

`name` `text ...`

`url` `text ...`

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

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

`已弃用`

`description` `text ...`

`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` `定义名称 [描述 ...]` ⇒ 参数

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

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

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

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

`response` `引用状态码`

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

`summary` `文本 ...`

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

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

`description` `text ...`

`example` `名称内容`

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

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

`title` `text ...`

`description` `描述 ...`

`description` `text ...`

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

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

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

`definition` `name` [type] ⇒ Schema

`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 ...]` ⇒ 标签

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

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

`version` `number` ⇒ 信息

`description` `text ...`

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