六、註釋：

一、SWG物件描述： @SWG\Swagger  宣告一個SWG全域性物件

固定欄位

例：

<?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版本資訊

三、請求操作物件描述： @SWG\Get/Post/Put/Delete 宣告一個介面請求資訊

描述路徑上的單個API操作。

固定欄位

例：

 /**

     *@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  描述一個單一的操作引數

固定欄位

五、響應物件描述： @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

固定欄位

例：

<?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;

}