一、SWG对象描述: @SWG\Swagger 声明一个SWG全局对象
固定字段
字段名称 | 类型 | 描述 |
| 需要。指定正在使用的Swagger规范版本。它可以被Swagger UI和其他客户端用来解释API列表。该值必须是 | |
需要。提供关于API的元数据。元数据可以由客户端使用,如果需要的话。 | ||
| 提供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;
}