swagger_php注释详解

六、注释：

一、SWG对象描述： @SWG\Swagger  声明一个SWG全局对象

固定字段

字段名称	类型	描述
swagger	string	需要。指定正在使用的Swagger规范版本。它可以被Swagger UI和其他客户端用来解释API列表。该值必须是"2.0"。
Info	信息对象	需要。提供关于API的元数据。元数据可以由客户端使用，如果需要的话。
host	string	提供API的主机（名称或IP）。这只能是主机，不包括方案和子路径。它可能包括一个端口。如果host不包括，将使用提供文档的主机（包括端口）。在host不支持路径模板。
bashpath	string	API所服务的基本路径，相对于host。如果没有包含，则直接在API下提供API host。该值必须以一个前导斜杠（/）开始。在basePath不支持路径模板。
schemes	string	API的传输协议。值必须是从列表："http"，"https"，"ws"，"wss"。如果schemes不包含，则使用的默认方案是用于访问规范的方案。
consumes	string	API可以使用的MIME类型列表。这对所有的API都是全局的，但是可以在特定的API调用上被覆盖。值必须如MIME类型下所述。
produces	string	API可以生成的MIME类型列表。这对所有的API都是全局的，但是可以在特定的API调用上被覆盖。值必须如MIME类型下所述。
paths	操作对象	需要。API的可用路径和操作。
definitions	定义对象	一个对象，用于保存操作生成和使用的数据类型。
parameters	参数定义对象	保存可在各个操作中使用的参数的对象。该属性没有为所有操作定义全局参数。
responses	响应定义对象	保存可用于各个操作的响应的对象。这个属性没有定义全局响应的所有操作。
securityDefinitions	安全定义对象	可以在规范中使用的安全方案定义。
security	安全要求对象	宣布哪些安全计划适用于整个API。值的列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。单独的操作可以覆盖这个定义。
tags	标签对象	规范使用附加元数据的标签列表。标签的顺序可以用来反映他们的解析工具的顺序。操作对象所使用的标签并非都必须声明。未声明的标签可以随机组织或基于工具的逻辑组织。列表中的每个标签名必须是唯一的。
externalDocs	外部文档对象	额外的外部文件。

例：

 

/**

 * @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.

以后大家就在这里愉快的对接口把!

以后大家就在这里愉快的对接口把!

以后大家就在这里愉快的对接口把!

"

 *   ),

 *

 *   @SWG\Tag(

 *     name="User",

 *     description="用户操作",

 *   ),

 *

 *   @SWG\Tag(

 *     name="MainPage",

 *     description="首页模块",

 *   ),

 *

 *   @SWG\Tag(

 *     name="News",

 *     description="新闻资讯",

 *   ),

 *

 *   @SWG\Tag(

 *     name="Misc",

 *     description="其他接口",

 *   ),

 * )

 */

二、信息对象描述： @SWG\Info  声明一个API版本信息

字段名称	类型	描述
title	string	需要。API的标题。
description	string	API的简短说明。
termsOfService	string	API的服务条款。
contact	联系对象	暴露的API的联系信息。
license	许可证对象	暴露的API的许可证信息。
version	string	必需提供应用程序API的版本（不要被规格版本混淆）。

三、请求操作对象描述： @SWG\Get/Post/Put/Delete 声明一个接口请求信息

描述路径上的单个API操作。

固定字段

字段名称	类型	描述
tags	string	接口名
summary	string	接口的简短摘要。为了在swagger-ui中获得最大的可读性，这个字段应该少于120个字符。
description	string	接口的详细解释。
externalDocs	外部文档对象	有关此操作的其他外部文档。
operationId	string	操作的友好名称。id必须在API中描述的所有操作中唯一。工具和库可以使用操作ID来唯一标识一个操作。
consumes	string	该操作可以使用的类型列表。这将覆盖consumesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述。
produces	string	操作可以产生的类型列表。这将覆盖producesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述。
parameters	参数对象	适用于此操作的参数列表。如果在路径项目中已经定义了一个参数，新的定义将覆盖它，但是不能删除它。该列表不得包含重复的参数。一个独特的参数是由一个名称和位置的组合来定义的。该列表可以使用引用对象链接到在Swagger对象参数中定义的参数。最多可以有一个“身体”参数。
responses	响应对象	需要。执行此操作时返回的可能响应列表。
schemes	string	操作的传输协议。值必须是从列表："http"，"https"，"ws"，"wss"。该值将覆盖Swagger对象schemes定义。
deprecated	boolean	声明此操作将被弃用。宣布的操作的使用应该被禁止。默认值是false。
security	安全要求对象	宣布哪些安全计划适用于此操作。值列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。该定义覆盖任何已声明的顶层security。要删除顶级安全声明，可以使用空数组。
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  描述一个单一的操作参数

固定字段

字段名称	类型	描述
name	string	需要。参数的名称。参数名称区分大小写。
in	string	需要。参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。
description	string	参数的简要说明。这可能包含使用的例子。
type	string	参数的类型。取值权限：“string”，“number”，“integer”，“bollean”，“array”，“file”。
required	boolean	确定此参数是否是必需的。其默认值是false。
defult	*	默认值。

五、响应对象描述： @SWG\Response  描述来自API操作的单个响应

 

固定字段

字段名称	类型	描述
description	string	需要。响应的简短描述。
schema	模式对象	响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。
headers	标题对象	与响应一起发送的标题列表。
examples	示例对象	响应消息的一个例子。

例：

@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

固定字段

字段名称	类型	描述
discriminator	string	添加对多态的支持。鉴别符是用于区分继承此模式的其他模式的模式属性名称。使用的属性名必须在这个模式中定义，并且必须在required属性列表中。使用时，值必须是该模式的名称或任何继承它的模式。
readOnly	boolean	仅与架构"properties"定义相关。声明该属性为“只读”。这意味着它可以作为响应的一部分发送，但不能作为请求的一部分发送。标记为属性readOnly的存在true不应该在该required定义的架构列表。默认值是false。
XML	XML对象	这只能用于属性模式。它对根模式没有影响。添加其他元数据来描述此属性的XML表示格式。
externalDocs	外部文档对象	此架构的其他外部文档。
example	*	一个自由格式的属性，包含这个模式的一个实例的例子

例：

/**

 * @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;

}