技術標籤：學習筆記經驗分享開發筆記php後端經驗分享程式人生恰飯

寫在前面：可能會遇到php的版本不支援，我這裡使用的是php7.1。

swagger是什麼

相信無論是前端還是後端開發，都或多或少地被介面文件折磨過。前端經常抱怨後端給的介面文件與實際情況不一致。後端又覺得編寫及維護介面文件會耗費不少精力，經常來不及更新。其實無論是前端呼叫後端，還是後端呼叫後端，都期望有一個好的介面文件。但是這個介面文件對於程式設計師來說，就跟註釋一樣，經常會抱怨別人寫的程式碼沒有寫註釋，然而自己寫起程式碼起來，最討厭的，也是寫註釋。所以僅僅只通過強制來規範大家是不夠的，隨著時間推移，版本迭代，介面文件往往很容易就跟不上程式碼了。

發現了痛點就要去找解決方案。解決方案用的人多了，就成了標準的規範，這就是Swagger的由來。通過這套規範，你只需要按照它的規範去定義介面及介面相關的資訊。再通過Swagger衍生出來的一系列專案和工具，就可以做到生成各種格式的介面文件，生成多種語言的客戶端和服務端的程式碼，以及線上介面除錯頁面等等。這樣，如果按照新的開發模式，在開發新版本或者迭代版本的時候，只需要更新Swagger描述檔案，就可以自動生成介面文件和客戶端服務端程式碼，做到呼叫端程式碼、服務端程式碼以及介面文件的一致性。

但即便如此，對於許多開發來說，編寫這個yml或json格式的描述檔案，本身也是有一定負擔的工作，特別是在後面持續迭代開發的時候，往往會忽略更新這個描述檔案，直接更改程式碼。久而久之，這個描述檔案也和實際專案漸行漸遠，基於該描述檔案生成的介面文件也失去了參考意義。所以作為Java屆服務端的大一統框架Spring，迅速將Swagger規範納入自身的標準，建立了Spring-swagger專案，後面改成了現在的Springfox。通過在專案中引入Springfox，可以掃描相關的程式碼，生成該描述檔案，進而生成與程式碼一致的介面文件和客戶端程式碼。這種通過程式碼生成介面文件的形式，在後面需求持續迭代的專案中，顯得尤為重要和高效。

安裝

首先進入您的專案，然後執行下面的命令會自動在專案中獲取到3.0的swagger

composer require zircote/swagger-php:*

會自動在專案的verdor中生成下面這個檔案

到這裡就已經安裝成功了。

現在來配置生成swagger.json的function，這個json檔案就是我們的註釋檔案生成的，我們通過訪問某個頁面就可以看到具體的效果了

現在開始~

在你的class前面加入這樣的一個程式碼

/**
 * @OA\Info(
 *     title="Auth API",
 *     version="1.0"
 * )
 */
 

 #這個是申明文件的標題及版本，注意：程式碼中只用加一個這個就可以了

在你的function中加入這樣的一個程式碼

public function create_swagger()
    {
        $path              = APP_PATH; //申明生成文件的路徑
        $swagger           = \OpenApi\scan($path); //初始化swagger生成函式
        $swagger_json_path = 'swagger.json'; //swagger的存放路徑，可以填相對地址
        $res = file_put_contents($swagger_json_path, $swagger->toJson()); //呼叫寫入json的方法
        //var_dump($res);
    }

至此你的swagger生成的方法就已經完成了。現在需要寫註釋文件用於去生成swagger檔案

在你要生成文件的前面加入這樣的一個註釋，具體的可以看官方文件

/**
     * @OA\Get(
     *     path="/api/api/getBanner", //當前方法的相對路徑（簡單來說就是通過url可以訪問的路徑）
     *     tags={"index"},
     *     summary="獲取輪播圖",
     *     description="獲取輪播圖",
     *     operationId="waiting",
     *     @OA\Response(
     *         response="default",
     *         description="201"
     *     ),
     *     @OA\RequestBody(
     *         description="請求的東西",
     *     )
     * )
     */

現在你已經生成了一個註釋的json檔案，那我們怎麼看到這個介面文件呢

首先下載swagger-ui，下方是下載地址，下載下來的東西很多，但是整體來說有用的只有dist這個資料夾裡面的東西，如果你在下個專案想用只需要將這個資料夾拷貝過去

下載地址：https://github.com/swagger-api/swagger-ui/

將dist放在你的public檔案中，可以隨便改個名字，就像下面這樣的

現在找到上圖中的index.html，修改一下swagger.json的路徑

<script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "../swagger.json", //將這個url修改為你的swagger.json所在的位置，可以填相對路徑
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>

現在可以通過訪問function生成你的json檔案了，我一般習慣在開發環境用定時任務去生成。

生成：url/api/cron/create_swagger
檢視文件：url/swagger-ui