Swagger框架 API文檔速成

Swagger 斯瓦格 / 絲襪哥

SwaggerHP_Build.png

Swagger中式漢語：
絲襪哥? 斯瓦格? 有沒有很熟悉，當然不是你想的 格瓦斯 那是飲料！
Swagger給人第一印象就是【最（hen）流（niu）行（bai）】；

我們?yōu)槭裁匆肧wagger文檔？
1.自動化文檔，代替手寫API的web工具，代替MarkDown、world文檔、還有比較low的微信講述哈哈
2.配合swagger-ui我們只需要把參數寫在注釋里面就生成了文檔
3.在線動態(tài)測試API接口，相當于postman一樣調用接口返回數據success/error/data
// 下面有兩種使用方式，都可以使用只要實現(xiàn)最終展示給前端文檔目的就可以

1. Swagger編輯json使用方法：

用 Composer 安裝在框架中使用

使用配置到 Laravel 框架中

使用 swagger-ui + swagger-edit
下載 Swagger-ui 只需要 dist 里面的文件放在項目根目錄 public 下并配置上路由使用訪問。
下載 Swagger-editor 只要 dist 目錄的東西和根目錄的index.html 按照官方OpenAPI規(guī)范給出的語法使用編輯。

2. 代碼注釋解析使用方法：

phpStorm安裝組件 (安裝組件Swagger Plugin 和 PHP Annotations)

第一個組件CodeGlance是（側欄代碼地圖）這個和swagger沒有關系
只需要安裝Swagger Plugin和PHP Annotations，安裝如果超時提示
Plugin Swagger Plugin was not installed: Cannot download無法下載：
查看解決方法：CSDN-phpStorm安裝組件超時

phpStorm組件.png

PHPStorm配置自動補全

配置IDE自動補全功能
配置IDE自動補全.png
配置IDE自動補全信息
  • 控制器里注釋用 (Abbreviation:swaggerController Description:swagger)
@SWG\Post(
*     path="/register",
*     tags={"User"},
*     summary="接口名稱",
*     description="接口描述信息",
*     operationId="register-store",
*     produces={"application/json"},
*     @SWG\Parameter(ref="#/parameters/Authorization"),
*     @SWG\Response(
*         response=200,
*         description="注冊成功",
*         @SWG\Schema(ref="#/definitions/success"),
*     ),
*     @SWG\Response(
*         response=422,
*         description="注冊失敗",
*     ),
* )
  • Parameter.php使用 (Abbreviation:swaggerParameter Description:swagger)
*******************************paraName
 * @SWG\Parameter(
 *    parameter="輸入框對應控制器尋找名",
 *    name="輸入框名稱",
 *    description="輸入框描述",
 *    in="header",        // 放在/header/query(鏈接)/formData/body/path
 *    type="string",      // integer/float/string/boolean/object/password(模糊輸入) byte(編碼的字符base64)
 *    format="string",    // integer/float/string/boolean/object/password(模糊輸入) byte(編碼的字符base64)
 *    required=true,      // 輸入框不能為空
 *    enum={"0",0,1},     // 可以加枚舉
 * ),
 * *******************************end
  • 接口詳情描述-first()單數據注釋用 (Abbreviation:swaggerDefinition-first Description:swagger)
@SWG\Definition(
*     definition="user-index",
*     type="object",
*     required={"status","code","message","data"},
*     @SWG\Property(
*         property="status",
*         type="boolean",
*         example="true",
*         description="請求狀態(tài)",
*     ),
*     @SWG\Property(
*         property="code",
*         type="integer",
*         example=200,
*         description="狀態(tài)碼",
*     ),
*     @SWG\Property(
*         property="message",
*         type="string",
*         example="操作成功",
*         description="狀態(tài)語義",
*     ),
*     @SWG\Property(
*         property="data",
*         type="object",
*         @SWG\Property(
*             property="id",
*             type="integer",
*             example=1,
*         ),
*         @SWG\Property(
*             property="user",
*             type="array",
*             @SWG\Items(
*                 type="object",
*                 @SWG\Property(
*                     property="user_id",
*                     type="integer",
*                     example=1,
*                 ),
*                 @SWG\Property(
*                     property="username",
*                     type="string",
*                     example="三腳貓",
*                 ),
*             ),
*         ),
*         @SWG\Property(
*             property="hello",
*             type="string",
*             example="helloWorld",
*         ),
*     ),
* ),
  • 接口詳情描述-get()多數據注釋用 (Abbreviation:swaggerDefinition-get Description:swagger)
@SWG\Definition(
 *     definition="user-userInfo-index",
 *     type="object",
 *     required={"status","code","message","data"},
 *     allOf={
 *          @SWG\Schema(
 *              required={"data"},
 *              @SWG\Property(
 *                  property="status",
 *                  type="boolean",
 *                  example="true",
 *                  description="請求狀態(tài)",
 *              ),
 *              @SWG\Property(
 *                  property="code",
 *                  type="integer",
 *                  example=200,
 *                  description="狀態(tài)碼",
 *              ),
 *              @SWG\Property(
 *                  property="message",
 *                  type="string",
 *                  example="操作成功",
 *                  description="狀態(tài)語義",
 *              ),
 *              @SWG\Property(
 *                  property="data",
 *                  type="array",
 *                  @SWG\Items(
 *                      type="object",
 *                      required={"user_id"},
 *                      @SWG\Property(
 *                          property="user_id",
 *                          type="integer",
 *                          example=1,
 *                          description="可有可無的字段描述",
 *                      ),
 *                      @SWG\Property(
 *                          property="username",
 *                          type="string",
 *                          example="三腳貓",
 *                      ),
 *                  ),
 *             ),
 *          )
 *     },
 * ),
  • 接口詳情描述-paginate()分頁數據注釋用 (Abbreviation:swaggerDefinition-get-paginate Description:swagger)
@SWG\Definition(
*     definition="user-update",
*     type="object",
*     required={"status","code","message","data"},
*     allOf={
*         @SWG\Schema(
*             required={"data"},
*             @SWG\Property(
*                 property="status",
*                 type="boolean",
*                 example="true",
*                 description="請求狀態(tài)",
*             ),
*             @SWG\Property(
*                 property="code",
*                 type="integer",
*                 example=200,
*                 description="狀態(tài)碼",
*             ),
*             @SWG\Property(
*                 property="message",
*                 type="string",
*                 example="操作成功",
*                 description="狀態(tài)語義",
*             ),
*             @SWG\Property(
*                 property="data",
*                 type="array",
*                 @SWG\Items(
*                     type="object",
*                     required={"user_id"},
*                     @SWG\Property(
*                         property="user_id",
*                         type="integer",
*                         example=1,
*                         description="可有可無的字段描述",
*                     ),
*                     @SWG\Property(
*                         property="username",
*                         type="string",
*                         example="三腳貓",
*                     ),
*                 ),
*             ),
*         ),
*         @SWG\Schema(ref="#/definitions/paginate"),
*     },
* ),
  • OAuth 公共使用 (Parameter.php)
 * *********************************token
 * @SWG\Parameter(
 *   parameter="Authorization",
 *   name="Authorization",
 *   description="oauth token",
 *   type="string",
 *   format="string",
 *   in="header",
 *   required=true
 * ),
 * *********************************end
  • Success 公共使用 (Definitions.php)
 * ************************************  success  **********************************
 * @SWG\Definition(
 *     definition="success",
 *     type="object",
 *     required={"status","code","message"},
 *     allOf={
 *          @SWG\Schema(
 *              @SWG\Property(
 *                  property="status",
 *                  type="boolean",
 *                  example="true",
 *                  description="請求狀態(tài)",
 *              ),
 *              @SWG\Property(
 *                  property="code",
 *                  type="integer",
 *                  example=200,
 *                  description="狀態(tài)碼",
 *              ),
 *              @SWG\Property(
 *                  property="message",
 *                  type="string",
 *                  example="操作成功",
 *                  description="狀態(tài)語義",
 *              ),
 *              @SWG\Property(
 *                  property="data",
 *                  type="string",
 *                  example="[]",
 *                  description="無數據返回",
 *              ),
 *          )
 *     },
 * ),
 * *********************************************************end
  • 分頁 公共使用 (Definitions.php # 引入語法 @SWG\Schema(ref="#/definitions/paginate"),)
 * ************************************  分頁  **********************************
 * @SWG\Definition(
 *      definition="paginate",
 *      type="object",
 *      required={"links","meta"},
 *      @SWG\Property(
 *          property="links",
 *          type="object",
 *          @SWG\Property(
 *              property="first",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="last",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="prev",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="next",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *      ),
 *      @SWG\Property(
 *          property="meta",
 *          type="object",
 *          @SWG\Property(
 *              property="current_page",
 *              type="integer",
 *              example=1,
 *          ),
 *          @SWG\Property(
 *              property="from",
 *              type="integer",
 *              example=2,
 *          ),
 *          @SWG\Property(
 *              property="last_page",
 *              type="integer",
 *              example=4,
 *          ),
 *          @SWG\Property(
 *              property="path",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="per_page",
 *              type="integer",
 *              example="18",
 *          ),
 *          @SWG\Property(
 *              property="to",
 *              type="integer",
 *              example=18,
 *          ),
 *          @SWG\Property(
 *              property="total",
 *              type="integer",
 *              example=5,
 *          ),
 *      ),
 * ),
 * *********************************************************end

解釋Swagger參數

/**
* 這是一個資源控制器的Show方法 .
* @param  int $id
* @return \App\Http\Resources\Product\GoodsShowResource
*
* @SWG\Get(
*    path="/goodsNorm/{id}",  //路由名稱
*    tags={"Product"},  //標簽名稱 eg: Http/Controller/Document/Product 里面放接口文檔Responses集合
*    operationId="goods-norm",  //用于識別操作url地址欄中顯示
*    summary="獲取商品",  //外面標題
*    description="獲取單個商品詳細數據",  //里面詳細標題
*    consumes={"application/json"},    //Mime類型常用的就這兩種 application/x-www-form-urlencoded
*    @SWG\Parameter(ref="#/parameters/Authorization"),  //可理解為參數定義路徑/Document/parameters.php
*    @SWG\Parameter(ref="#/parameters/common-id"),      //同上
*    @SWG\Response(                                     //必填的響應對象
*        response=200,                                  //響應的狀態(tài)碼
*        description="成功獲單個商品",                   //響應后的提示
*        @SWG\Schema(ref="#/definitions/goods-norm")    //響應成功后的參數示例
*    )
*    @SWG\Response(
*        response=404,
*        description="沒有找到您要詳細參數的數據",
*    )
* )
*/
public function show($id){
      //@#$%^&**  業(yè)務邏輯層

      //API資源返回json數據格式 （詳情見Laravel5.5手冊 Eloquent ORM的API資源）
      return new GoodsNormResource($detail);
}

解釋參數構造->Parameter.php

@SWG\Parameter(ref="#/parameters/Authorization")
文件夾路徑：app/Http/Controller/Document/parameters.php

<?php
/**
 ************************************  token  **********************************
 * @SWG\Parameter(
 *   parameter="Authorization",      //Authorization 名稱，用來在方法注釋尋找
 *   name="Authorization",          //千萬別用漢字，如果在傳id的時候會解析錯誤
 *   description="oauth token",    //inuput輸入框描述
 *   type="string",     //數據類型 integer string boolean password模糊輸入 float數字 byte編碼的字符base64
 *   format="string",  //同上，不知道干嘛的，寫上錯不了- -
 *   in="header",     //
 *   required=true  //輸入框不能為空
 * ),
 ************************************  common  **********************************
 * @SWG\Parameter(
 *    parameter="common-id",
 *    name="id",
 *    in="path",
 *    type="integer",
 *    description="ID",
 *    required=true
 * ),

返回json語法定義->definitions.php

@SWG\Schema(ref="#/definitions/goods-norm")
文件夾路徑：app/Http/Controller/Document/definitions.php

<?php
/**
 * @SWG\Definition(
 *      definition="201",
 *      required={"message"},
 *      @SWG\Property(
 *          property="message",
 *          type="string",
 *          example="創(chuàng)建成功"
 *      )
 * ),
 ************************************  204  **********************************
 * @SWG\Definition(
 *      definition="204",
 *      required={"message"},
 *      @SWG\Property(
 *          property="message",
 *          type="string",
 *          example="刪除成功"
 *      )
 * ),

Definition @SWG\Schema(ref="#/definitions/json-json"),

  • json下放json
 * @SWG\Definition(
 *     definition="json-json",
 *     required={"json"},
 *     type="object",
 *     allOf={
 *          @SWG\Schema(
 *              @SWG\Property(
 *                  property="json",
 *                  type="object",
 *                  description="json字段",
 *                  required={"name"},
 *                  @SWG\Property(
 *                       property="name",
 *                       type="string",
 *                       example="三腳貓",
 *                       description="用戶名",
 *                  ),
 *              ),
 *          ),
 *     },
 * ),
 ************************************  Demo  **********************************
{
  "json":{
    "name":"三腳貓",
  }
}
  • json下放數組
 * @SWG\Definition(
 *     definition="json-array",
 *     required={"json"},
 *     type="object",
 *     allOf={
 *          @SWG\Schema(
 *              required={"json"},
 *              @SWG\Property(
 *                  property="json",
 *                  type="array",
 *                  description="json字段",
 *                  required={"name"},
 *                  @SWG\Items(
 *                      @SWG\Property(
 *                          property="name",
 *                          type="string",
 *                          example="三腳貓",
 *                          description="用戶名",
 *                      ),
 *                  ),
 *              ),
 *          ),
 *     },
 * ),
 ************************************  Demo  **********************************
{
  "json":{[
    "name":"三腳貓"
  ],[
    "name":"三腳貓"
  ],}
}

以上都是blog里復制出來的，有些文字不必在意，知道是代表的什么意思就好啦。有問題留言~

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
【社區(qū)內容提示】社區(qū)部分內容疑似由AI輔助生成，瀏覽時請結合常識與多方信息審慎甄別。
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發(fā)布，文章內容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務。

友情鏈接更多精彩內容