一、SWG对象描述： @SWG\Swagger 声明一个SWG全局对象
固定字段
| 字段名称 |
类型 |
描述 |
|
|
需要。指定正在使用的Swagger规范版本。它可以被Swagger UI和其他客户端用来解释API列表。该值必须是 |
|
| 需要。提供关于API的元数据。元数据可以由客户端使用，如果需要的话。
扫描二维码关注公众号，回复：
5968306 查看本文章
|
||
|
|
提供API的主机（名称或IP）。这只能是主机，不包括方案和子路径。它可能包括一个端口。如果 |
|
|
|
API所服务的基本路径，相对于 |
|
|
|
API的传输协议。值必须是从列表： |
|
|
|
API可以使用的MIME类型列表。这对所有的API都是全局的，但是可以在特定的API调用上被覆盖。值必须如MIME类型下所述。 |
|
|
|
API可以生成的MIME类型列表。这对所有的API都是全局的，但是可以在特定的API调用上被覆盖。值必须如MIME类型下所述。 |
|
| 需要。API的可用路径和操作。 |
||
| 一个对象，用于保存操作生成和使用的数据类型。 |
||
| 保存可在各个操作中使用的参数的对象。该属性没有为所有操作定义全局参数。 |
||
| 保存可用于各个操作的响应的对象。这个属性没有定义全局响应的所有操作。 |
||
| 安全定义对象 |
可以在规范中使用的安全方案定义。 |
|
| 宣布哪些安全计划适用于整个API。值的列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。单独的操作可以覆盖这个定义。 |
||
| 规范使用附加元数据的标签列表。标签的顺序可以用来反映他们的解析工具的顺序。操作对象所使用的标签并非都必须声明。未声明的标签可以随机组织或基于工具的逻辑组织。列表中的每个标签名必须是唯一的。 |
||
| 额外的外部文件。 |
例：
<?php
/**
* @SWG\Swagger(
* schemes={"http"},
* host="api.my_project.com",
* consumes={"multipart/form-data"},
* produces={"application/json"},
* @SWG\Info(
* version="2.3",
* title="my project doc",
* description="my project 接口文档, V2-3.<br>
* 以后大家就在这里愉快的对接口把!<br>
* 以后大家就在这里愉快的对接口把!<br>
* 以后大家就在这里愉快的对接口把!<br>"
* ),
* @SWG\Tag(
* name="User",
* description="用户操作",
* ),
*
* @SWG\Tag(
* name="MainPage",
* description="首页模块",
* ),
* @SWG\Tag(
* name="News",
* description="新闻资讯",
* ),
* @SWG\Tag(
* name="Misc",
* description="其他接口",
* ),
* )
*/
二、信息对象描述： @SWG\Info 声明一个API版本信息
| 字段名称 |
类型 |
描述 |
|
|
需要。API的标题。 |
|
|
|
API的简短说明。 |
|
|
|
API的服务条款。 |
|
| 暴露的API的联系信息。 |
||
| 暴露的API的许可证信息。 |
||
|
|
必需提供应用程序API的版本（不要被规格版本混淆）。 |
三、请求操作对象描述： @SWG\Get/Post/Put/Delete 声明一个接口请求信息
描述路径上的单个API操作。
固定字段
| 字段名称 |
类型 |
描述 |
|
|
接口名 |
|
|
|
接口的简短摘要。为了在swagger-ui中获得最大的可读性，这个字段应该少于120个字符。 |
|
|
|
接口的详细解释。 |
|
| 有关此操作的其他外部文档。 |
||
|
|
操作的友好名称。id必须在API中描述的所有操作中唯一。工具和库可以使用操作ID来唯一标识一个操作。 |
|
|
|
该操作可以使用的类型列表。这将覆盖 |
|
|
|
操作可以产生的类型列表。这将覆盖 |
|
| 适用于此操作的参数列表。如果在路径项目中已经定义了一个参数，新的定义将覆盖它，但是不能删除它。该列表不得包含重复的参数。一个独特的参数是由一个名称和位置的组合来定义的。该列表可以使用引用对象链接到在Swagger对象参数中定义的参数。最多可以有一个“身体”参数。 |
||
| 需要。执行此操作时返回的可能响应列表。 |
||
|
|
操作的传输协议。值必须是从列表： |
|
|
|
声明此操作将被弃用。宣布的操作的使用应该被禁止。默认值是 |
|
| 宣布哪些安全计划适用于此操作。值列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。该定义覆盖任何已声明的顶层 |
||
| path |
URl |
接口请求的路由 |
例：
/**
*@SWG\Post(path="/user/login", tags={"User"},
* summary="登录接口(用户名+密码)",
* description="用户登录接口,账号可为 用户名 或 手机号. 参考(这个会在页面产生一个可跳转的链接: [用户登录注意事项](http://blog.csdn.net/liuxu0703/)",
* @SWG\Parameter(name="userName",type="string", required=true, in="formData",
* description="登录用户名/手机号"
* ),
* @SWG\Parameter(name="password",type="string", required=true, in="formData",
* description="登录密码"
* ),
* @SWG\Parameter(name="image_list",type="string", required=true, in="formData",
* @SWG\Schema(type="array",@SWG\Items(ref="#/definitions/Image")),
* description="用户相册. 好吧,没人会在登录时要求填一堆图片信息.这里是为了示例 带结构的数据, @SWG\Schema ,这个结构需要另行定义,下面会讲."
* ),
* @SWG\Parameter(name="video",type="string", required=true, in="formData",
* @SWG\Schema(ref="#/definitions/Video"),
* description="用户 呃... 视频? 同上,为了示例 @SWG\Schema ."
* ),
* @SWG\Parameter(name="client_type",type="integer", required=false, in="formData",
* description="调用此接口的客户端类型: 1-Android, 2-IOS. 非必填,所以 required 写了false"
* ),
* @SWG\Parameter(name="gender",type="integer", required=false, in="formData",
* default="1",
* description="性别: 1-男; 2-女. 注意这个参数的default上写的不是参数默认值,而是默认会被填写在swagger页面上的值,为的是方便用swagger就地访问该接口."
* ),
* )
*/
public functionloginAction() {
// php code
}
/**
*@SWG\Get(path="/User/myWebPage", tags={"User"},
* produces={"text/html"},
* summary="用户的个人网页",
* description="这不是个api接口,这个返回一个页面,所以 produces 写了text/html",
* @SWG\Parameter(name="userId",type="integer", required=true, in="query"),
* @SWG\Parameter(name="userToken",type="string", required=true, in="query",
* description="用户令牌",
* ),
* )
*/
public functionmyWebPageAction(){
// php code
}
四、参数对象描述： @SWG\Parameter 描述一个单一的操作参数
固定字段
| 字段名称 |
类型 |
描述 |
|
|
需要。参数的名称。参数名称区分大小写。 |
|
|
|
需要。参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。 |
|
|
|
参数的简要说明。这可能包含使用的例子。 |
|
| type |
|
参数的类型。取值权限：“string”，“number”，“integer”，“bollean”，“array”，“file”。 |
|
|
确定此参数是否是必需的。其默认值是 |
|
| defult |
|
默认值。 |
五、响应对象描述： @SWG\Response 描述来自API操作的单个响应
固定字段
| 字段名称 |
类型 |
描述 |
|
|
需要。响应的简短描述。 |
|
| 响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。 |
||
| 与响应一起发送的标题列表。 |
||
| 响应消息的一个例子。 |
例：
@SWG\Response(response="default", description="操作成功")
七、模式对象描述： @SWG\Schema 允许定义输入输出数据类型
常用限制：
- ref
- format
- title
- description
- default
- multipleOf
- maximum
- exclusiveMaximum
- minimum
- exclusiveMinimum
- maxLength
- minLength
- pattern
- maxItems
- minItems
- uniqueItems
- maxProperties
- minProperties
- required
- enum
- type
固定字段
| 字段名称 |
类型 |
描述 |
|
|
添加对多态的支持。鉴别符是用于区分继承此模式的其他模式的模式属性名称。使用的属性名必须在这个模式中定义，并且必须在 |
|
|
|
仅与架构 |
|
| 这只能用于属性模式。它对根模式没有影响。添加其他元数据来描述此属性的XML表示格式。 |
||
| 此架构的其他外部文档。 |
||
| example |
* |
一个自由格式的属性，包含这个模式的一个实例的例子 |
例：
<?php
/**
* @SWG\Definition(type="object",@SWG\Xml(name="Image"))
*/
class Image {
/**
* @SWG\Property()
* @var string
*/
public $url;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $height;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $width;
}