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规范兼容，该规范是开放API倡议的基础。

安装

需要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_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）的语句。

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

您可以使用 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` `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 ...]` ⇒ BodyParameter

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

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

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

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

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

`已弃用`

将此操作标记为已弃用。

`description` `text ...`

设置操作的详细描述。

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

设置指向更多文档的URL。

别名: docs

`error` `statuscode [description]` ⇒ Error

添加此操作可能返回的可能错误状态码，包括可选的描述文本。

如果没有提供描述，则将使用状态码的标准原因。

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

添加此操作可能返回的几个可能错误状态码。

`form`/`form?` `definition name [description ...]` ⇒ Parameter

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

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

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

`header`/`header?` `definition name [description ...]` ⇒ Parameter

为此操作添加新的头参数。

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

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

`id` `name`

为此操作设置操作ID。

name ID名称必须在文档中的所有操作中是唯一的。如果您指定了一个已经设置的ID，将抛出异常。

`parameter` `name`

通过引用全局定义的参数的名称添加新的参数。

name 参数引用的全局唯一名称。

别名: param

`path` `definition name [description ...]` ⇒ Parameter

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

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

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

响应

表示响应。

`example` `名称内容`

向响应添加一个示例。

name 示例的唯一单字（无空格）名称。每个响应唯一。

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

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

向响应添加一个头部。

type 必须是 string、number、integer、boolean 或 array。

name 必须是有效的HTTP头部名称。例如：X-Rate-Limit-Limit。

模式

表示类型定义，如数组。

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

设置指向更多文档的URL。

别名: docs

`title` `text ...`

设置此模式标题。

`description` `描述 ...`

设置此模式描述。

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

安全方案

表示用户/客户端到服务器的单种认证方式。您使用 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` `名称` [类型] ⇒ 模式

使用指定的参考名称开始定义模式。

可以使用感叹号在定义命令的末尾指定只读定义。例如：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 ...]` ⇒ 许可证

设置此 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

类型：字符串或二进制,
范围：[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个二进制位，至少需要1个。

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

表示没有小数的数字。

type[0,>=default

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

命令

default 值设置默认值。
enum value1 value2 ... valueN设置或添加允许的值。
step 值设置数字之间的步长。

示例

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

浮点数、双精度浮点数

表示带有小数的浮点数。

type[0,>=default

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

命令

default 值设置默认值。
enum value1 value2 ... valueN设置或添加允许的值。
step 值设置数字之间的步长。

示例

float无默认值或限制范围的32位浮点数。
double<,1>最多（但不包括）1的64位浮点数。
float<0,>=0.132位正数，不包括0，默认为0.1。

布尔型（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值表示零。空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

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

示例

file 一个文件。

object

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

object(definition)[0,>

替代简写符号

{definition}[0,>

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

命令

min 值设置所需的最小项目数。
max 值设置允许的最大项目数。
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)

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

命令

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

示例

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

enum

特殊的字符串类型，其值限于预定义值之一。

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

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

许可证

提供了一些许可证的缩写。如果你想添加其他许可证，请提交一个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
}

danijelsingularity98 / 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 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 ...] ⇒ BodyParameter

consumes mime1 [mime2 ... mimeN]

已弃用

description text ...

doc url [description ...] ⇒ ExternalDocumentation

error statuscode [description] ⇒ Error

errors statuscode1 [statuscode2 ... statuscodeN]

form/form? definition name [description ...] ⇒ Parameter

header/header? definition name [description ...] ⇒ Parameter

id name

parameter name

path definition name [description ...] ⇒ Parameter

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

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

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

`已弃用`

`description` `text ...`

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

`error` `statuscode [description]` ⇒ Error

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

`form`/`form?` `definition name [description ...]` ⇒ Parameter

`header`/`header?` `definition name [description ...]` ⇒ Parameter

`id` `name`

`parameter` `name`

`path` `definition name [description ...]` ⇒ Parameter

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

`title` `text ...`

`description` `描述 ...`

`description` `text ...`

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

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

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

`definition` `名称` [类型] ⇒ 模式

`description` `text ...` ⇒ Info

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

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

`title` `text ...` ⇒ Info

`version` `number` ⇒ Info

`description` `text ...`

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