利用swagger打造高可用項目文檔——PHP篇

你是否也被沒有文檔的項目折磨？你是否也由於項目須要寫文檔而頭疼？你是否也被年久失修的文檔坑害？少年，吃下我這發安利吧！經過部署 Swagger，這些問題都將遠離你，精美、易讀、可測試、時效性高的文檔，不想試試麼？

效果展現

閒言少敘，咱們直接來看最終的效果，黑喂狗！

step1.給接口添加註釋

註釋語句的語法後續有機會再討論，這裏不作贅述。

step2.查看根據註釋自動生成的Json結構

step3.根據Json結構自動生成文檔

step4.能夠經過文檔進行接口調用測試

原由

做爲一名開發人員，寫文檔真的是一件很痛苦的事情，主要痛點有以下幾個（我的觀點）:

• 與開發工做分離，寫文檔的過程當中，須要在文檔與代碼間切換。低效
• 對於代碼進行邏輯更新後，還須要在另外一個地方更新文檔。麻煩
• 已經對代碼添加過完整的註釋，還須要從新翻譯成文檔。工做重複

其實總結一下，就一個字——懶。

基於以上幾點，樓主開始思考，有沒有什麼工具，能夠以註釋爲基礎自動生成文檔？若是有的話，就能夠減小研發生產文檔的時間，避免重複工做，而且能夠保證文檔的可用性（避免文檔年久失修）。

swagger介紹

首先來看下官方定義

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

簡單來講，Swagger 實際上是一種接口的描述規範，只要按照這個規範對接口進行描述，添加註釋，即可以產出結構化的數據，而後使用 Swagger 官方提供的工具即可以產出精美的接口文檔。因此引言中提到的 '部署Swagger' ，準確來講，應該是 '部署Swagger規範'。

文檔生成思路

不論是什麼語言或者項目，均可以按照這個思路來生成文檔，本篇文章只描述 PHP 項目具體實施步驟。

部署

• 項目中引入SDK

  composer require zircote/swagger-php
  複製代碼

• 接口添加註釋

  引入後直接按照 SDK的規範在接口上添加註釋便可，能夠參考：
  Swagger-php-example

  提供一個簡單例子，以laravel/lumen框架爲例
    
    <?php
    	namespace App\Http\Controllers;
  
    	use Illuminate\Http\Request;
  
    	class ExampleController extends Controller
    	{
    		/**
    		 * 這個一個須要實現的API
    		 * 
    		 * 這部分是項目的基本描述，對於一個項目來講必需要有
    		 * 因爲是示例代碼，因此把項目描述也放在了接口描述中，其實能夠將這部分拆離到單獨的文件中
    		 * @SWG\Swagger(
    		 *     schemes={"http"},
    		 *     host="somehost.webdev.com",
    		 *     basePath="/api",
    		 *     @SWG\Info(
    		 *         title="這是一個測試項目",
    		 *         version="1.0.0",
    		 *         @SWG\Contact(
    		 *            email="test@email.com"
    		 *         )
    		 *     )
    		 * )
    		 * 
    		 * 接下來是針對接口的描述
    		 * @SWG\Get(
    		 *     path="/v1/getsomething",
    		 *     summary="這裏是接口描述",
    		 *     produces={"application/json"},
    		 *     參數1
    		 *     @SWG\Parameter(
    		 *         description="頁碼",
    		 *         in="query",
    		 *         name="pageNum",
    		 *         type="number",
    		 *         required=true
    		 *     ),
    		 *     參數2
    		 *     @SWG\Parameter(
    		 *         description="頁面內容數",
    		 *         in="query",
    		 *         name="pageSize",
    		 *         type="number"
    		 *     ),
    		 *     響應體
    		 *     @SWG\Response(
    		 *         response=200,
    		 *         description="Success",
    		 *         // 也能夠添加返回數據的示例，這裏不作贅述
    		 *     )
    		 *     響應體
    		 *     @SWG\Response(
    		 *         response=404,
    		 *         description="Not Found",
    		 *     )
    		 * )
    		 */
    		public function getSomeThing(Request $request)
    		{
    			// todo 待實現
    		}
    	}
  複製代碼

  複製上邊的例子，此時咱們便有了一個擁有標準結構註釋的接口。

• 構造調用接口

  註釋構建好了之後，那麼接下來就是產出 Swagger標準的數據了，這裏咱們選用 Json作爲產出結構。

  爲了方便起見，咱們將得到 Json數據的邏輯封裝爲接口，這樣就能夠隨時隨地拿到這個標準 Swagger Json了，以 Laravel/Lumen框架爲例，簡單例子以下：

  <?php
    	namespace App\Http\Controllers;
  
    	class SwaggerController extends Controller
    	{
    		public function getSwaggerJson()
    		{
    		   // 該函數會掃描配置的目錄地址下的文件，並將其中標準化的註釋渲染爲json數據
    			$swagger = \Swagger\scan(['須要掃描的目錄1', '須要掃描的目錄2', ...]);
  
    			return response()->json($swagger, 200);
    		}
    	}
  複製代碼

  再提供一個官方 Json數據做參考：官方參考

  此時即可以經過該接口獲取標準 Swagger Json了，接下來就是作數據展現的問題了。

• 接口文檔展現

  起初想到的展現方法是將官方提供的 Swagger-ui搭建成一個服務，而後提供統一入口，後來以爲這種方法過於侷限，沒法隨時隨地去查看文檔，還要去記錄服務地址。

  後來設想，是否可使用 Chrome插件來實現這個事情？調研了一番，果真有前人走了這條路，已經有現成的插件可使用。

  Swagger-ui插件

  安裝好插件後，如文章開頭展現的，在接口頁面的基礎上，點擊打開 Swagger-ui插件便可獲得文檔，而且能夠進行接口測試等操做。

  至此，一個簡單、高效的 Swagger環境就搭建好了，具體怎麼使用，就看你們本身的喜愛了。Hope you enjoy it!

可參考文檔

Swagger-php SDK

Swagger-ui 有須要的同窗能夠本身搭建Swagger-ui

Swagger官網

Swagger標準的參數解釋

Swagger OpenAPI 規範