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 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)`

通过扫描提供的files列表生成Swagger/OpenAPI文档。您可以指定额外的dirs来扫描类文件，并提供一个format来指定您希望输出的文档格式。

默认情况下，文档以数组形式输出，准备编码为JSON、YAML或手动后处理。以下格式作为SwaggerGen类的常量可用。

FORMAT_ARRAY输出原始数组。
FORMAT_JSONJSON编码输出（MIME类型application/json）。
FORMAT_JSON_PRETTY带有适合人类阅读布局的JSON编码输出（MIME类型application/json）。
FORMAT_YAMLYAML（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，也不会区分静态和动态的 :: 和 ->。这些可以互换使用，不会产生影响。尽管建议坚持使用适当的术语。

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

别名：see

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

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

扩展没有额外的功能，并被当作原始的文本数据块处理。

BodyParameter

表示一个请求体参数。

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

Contact

包含 API 的联系信息。

`email` `email`

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

`name` `text ...`

设置联系人的姓名。

`url` `email`

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

Error

表示带有错误状态码的响应。

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

ExternalDocumentation

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

`description` `text ...`

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

`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` `文本 ...`

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

别名：tos、termsofservice

`title` `文本 ...`

设置API标题。

`version` `数字`

设置API版本号。

许可证

表示适用于API的许可证的名称和URL。

`name` `文本 ...`

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

`url` `文本 ...`

设置许可证的URL。

操作

描述一个操作；使用特定方法调用特定路径。

`body`/`body?` `定义名称 [描述 ...]` ⇒ 主体参数

为此操作添加一个新的表单参数。

使用body使参数成为必需的。使用body?（带有问号）使参数成为可选的。

请参阅参数定义章节，以了解所有可能的定义格式的详细说明。

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

添加此操作能够理解的多媒体类型。例如："application/json"、"multipart/form-data"或"application/x-www-form-urlencoded"。

`deprecated`

将此操作标记为已弃用。

`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?` `definition name [description ...]` ⇒ 参数

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

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

请参阅参数定义章节，以了解所有可能的定义格式的详细说明。

`require` `security1 [security2 ... securityN]`

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

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

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

添加可能的状态码和将要返回的数据定义。虽然对于错误状态码通常使用 error 或 errors 命令，但您也可以使用此命令，包括返回定义。

请参阅参数定义章节，以了解所有可能的定义格式的详细说明。

`response` `参考状态码`

参考响应定义。

reference 名称必须在 Swagger 上下文中定义为一个响应定义。

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

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

将任意数量的方案添加到操作中。

`summary` `文本 ...`

设置操作的简短摘要描述。

`tags` `tag1 [tag2 ... tagN]`

将任意数量的标签添加到操作中。

参数

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

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

路径

表示 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 [描述 ...]` ⇒ 外部文档

设置指向更多文档的URL。

别名: docs

`title` `文本 ...`

设置此模式的标题。

`description` `description ...`

设置此模式的描述。

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

SecurityScheme

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

`description` `text ...`

设置描述。

`scope` `name [description ...]`

添加带有可选描述的新OAuth2作用域名称。

Swagger

表示整个API文档。这是命令的初始上下文。

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

添加API能够理解的MIME类型。例如："application/json"、"multipart/form-data"或"application/x-www-form-urlencoded"。

别名：consume

`contact` `[url] [email] [name ...]` ⇒ Contact

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

设置指向更多文档的URL。

别名: docs

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

使用/path创建端点。如果设置了标记，则端点将被分配给该名称的标记组。如果设置了描述，则将设置组的描述。

`license` `[url] [name ...]` ⇒ License

为此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

添加一个具有返回数据模式定义的响应定义。您可以通过指定 null 来省略 definition。

请参阅参数定义章节，以了解所有可能的定义格式的详细说明。

`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 ...` ⇒ Info

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

别名：tos、termsofservice

`title` `text ...` ⇒ Info

设置API标题。

`version` `number` ⇒ Info

设置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] 至少1位二进制数字，最多8位。

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。

date, date-time (datetime)

仅限于日期的特殊字符串类型

type=default

类型：date，date-time 或 datetime，
默认值：任何由 PHP DateTime 对象识别的有效日期格式。

命令

default date 设置默认值。

示例

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 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,>

类型：object。
范围：[最小值，最大值]。使用 [ 或 ] 表示包含，使用 < 或 > 表示排除。空的 min 值表示零属性（无最小值）。空的 max 值表示无限属性（无最大值）。
定义：以 key:definition 形式分隔的属性定义列表，其中 key 可以是任何字符序列，但不能包含 : 或 ? 或 !。其中 ? 表示键是可选的。其中 ! 表示键是只读的。只读意味着可选。

命令

min value 设置所需项目的最小数量。
max value 设置允许的项目最大数量。
property definition name 添加必需的属性。
property? 定义名称 添加一个可选属性。
property! 定义名称 添加一个只读属性。
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)

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

命令

item 类型 将类型添加到 allOf 类型列表中

示例

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

definitionName：全局定义的 definition 的名称。

示例

refobject(Address) 引用名为 Address 的全局定义模型。
Address 引用名为 Address 的全局定义模型。

注释

通常情况下，仅使用定义名称就足够了。如果您使用的是也用作内置参数类型的名称，例如string或object，请使用refobject(...)。最好的做法是将所有定义名称的首字母大写（例如Address）。使用refobject(...)还可以提供最安全的向前兼容策略，如果您不以大写字母开始定义名称（例如address）。

附录

媒体类型

一些命令，例如consumes和produces，将媒体类型作为参数。您可以使用以下预定义的缩写（不区分大小写）来代替指定完整的媒体类型：

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

许可证

可用的缩写包括许可证。如果您想添加其他许可证，请提交一个issue或创建一个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
}

danijelsingulatiry98 / 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

Error

ExternalDocumentation

description text ...

url url

Header

description 文本 ...

信息

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

description 文本 ...

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

terms 文本 ...

title 文本 ...

version 数字

许可证

name 文本 ...

url 文本 ...

操作

body/body? 定义名称 [描述 ...] ⇒ 主体参数

consumes mime1 [mime2 ... mimeN]

deprecated

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? definition name [description ...] ⇒ 参数

require security1 [security2 ... securityN]

response 状态码定义描述 ⇒ 响应

response 参考状态码

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

summary 文本 ...

tags tag1 [tag2 ... tagN]

参数

路径

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

description 文本 ...

响应

example 名称 内容

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

模式

doc url [描述 ...] ⇒ 外部文档

title 文本 ...

`__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` `文本 ...`

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

`description` `文本 ...`

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

`terms` `文本 ...`

`title` `文本 ...`

`version` `数字`

`name` `文本 ...`

`url` `文本 ...`

`body`/`body?` `定义名称 [描述 ...]` ⇒ 主体参数

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

`deprecated`

`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?` `definition name [description ...]` ⇒ 参数

`require` `security1 [security2 ... securityN]`

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

`response` `参考状态码`

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

`summary` `文本 ...`

`tags` `tag1 [tag2 ... tagN]`

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

`description` `文本 ...`

`example` `名称内容`

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

`doc` `url [描述 ...]` ⇒ 外部文档

`title` `文本 ...`

`description` `description ...`

`description` `text ...`

`scope` `name [description ...]`

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

`contact` `[url] [email] [name ...]` ⇒ Contact

`definition` `name` [type] ⇒ Schema

`description` `text ...` ⇒ Info

`doc` `url [description ...]` ⇒ ExternalDocumentation

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

`license` `[url] [name ...]` ⇒ License

`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 ...` ⇒ Info

`title` `text ...` ⇒ Info

`version` `number` ⇒ Info

`description` `text ...`

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