PHP與 RESTful風格的swagger結合生成API
版權聲明：本文爲博主原創文章，未經博主允許不得轉載。
1. 什麼是RESTful風格
1.官方解釋：
一種軟件架構風格，設計風格而不是標準，只是提供了一組設計原則和約束條件。它主要用於客戶端和服務器交互類的軟件。基於這個風格設計的軟件可以更簡潔，更有層次，更易於實現緩存等機制。（好吧！官方就是官方，果然聽不懂～）
2.別人靠譜的理解:
是通過具體的URI定位符，找到對應的資源，然後以固定的格式返回數據，這樣的纔是Restful API；
3.我的理解:
既然叫風格，所見及風格。通過不同顏色區分不同的url請求，並通過URL定位去請求後臺對應的資源並返回相應的數據格式。
2.爲什麼用RESTful風格開發接口呢
1.無狀態，這點非常重要。在調用一個接口（訪問、操作資源）的時候，可以不用考慮上下文，不用考慮當前狀態，極大的降低了複雜度。（這句話感覺很經典，直接引用知乎上的這句）。
2.每一個URI代表一種資源，就像面嚮對象語言一切都是對象一樣，RESTful API一切都是資源。通過請求某一個url就能獲取到你想要的東西。
3.所見即所得，很美觀（自認爲，嘿嘿）；
3.爲什麼選擇SWAGGER
1.我之前也用過其他的接口文檔，綜合來說，跟swagger相比，頁面就是醜。你讓追求美感的前端攻城獅怎麼用。so chose swagger。
哈哈，在下邊
支持API自動生成同步的在線文檔
這些文檔可用於項目內部API審覈
方便測試人員瞭解API
這些文檔可作爲客戶產品文檔的一部分進行發佈
支持API規範生成代碼，生成的客戶端和服務器端骨架代碼可以加速開發和測試速度
跟其他API文檔工具相比，Swagger各有優缺點，但它功能最多、也是最流行的。
4.廢話少說，看效果
怎麼樣，就是好看。
扯了這麼多，下邊開始搭建環境。我用thinkphp5給大家搭建一個測試案例，會一步一步從頭開始。
5.測試案例
第一步
請大家先將TP5框架搭建完成，這個自己上TP官網上自己搞。
第二部
從swagger官網或者github上下載兩個文件swagger-ui,swagger-php，將這兩個文件整合到TP5框架裏，效果如如下：
直接扔到根目錄下就可以。
第三部
修改swagger-ui下dist下index.html裏邊的url，需要指向你的代碼經過swagger-php轉化成json後所存放的文件。我的代碼經過轉化後放在了swagger-php下的docs文件夾下的swagger.json文件裏了。swagger.json也是隨便起的名字，只要存放的是json文件就行。
1.swagger-php的作用就是將固定格式的php代碼轉化生成swagger-ui能夠讀懂的json文件。
2.所有的接口文件都要轉化成swagger-ui能夠讀取的json形式才能夠生成好看的接口文檔。（你有一萬個接口，都會生成json文件存放到這個swagger.json文件裏）。
這個json文件swagger-ui才能讀取，並生成好看的界面。
到這一步，你還無法生成json文件，需要一個入口文件。這個入口文件就在swagger-php的demo裏。
將這個入口文件稍加改造
我在下邊新創建了一個模塊，你們用自帶的index都行，然後我又創建了一個文件夾，然後給這個入口文件改了一個名字，叫compile_enter.php（編譯入口）,其實直接把他扔進模塊文件夾裏就行，不用這麼麻煩，只要掃描該模塊下有這個入口文件就行，主要怕看着亂。host改成你的域名，basepath拼接上訪問路徑/public/模塊名
<?php
/**
* @SWG\Swagger(
* schemes={"http"},
* host="www.pretty.com:80",
* basePath="/public/prettyinterface",
* @SWG\Info(
* version="1.0.0",
* title="Swagger Petstore",
* description="This is a sample server Petstore server. You can find out more about Swagger at <a href=""http://swagger.io"">http://swagger.io</a> or on irc.freenode.net, #swagger. For this sample, you can use the api key ""special-key"" to test the authorization filters",
* termsOfService="http://helloreverb.com/terms/",
* @SWG\Contact(
* email="apiteam@wordnik.com"
* ),
* @SWG\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* ),
* @SWG\ExternalDocumentation(
* description="Pretty",
* url="http://swagger.io"
* )
* )
*/
prettyinterface這是我的模塊名。
下邊打開cmd命令窗口，進行json文件的編譯轉換
這個命令分爲四個部分，php告訴程序這是用php執行並解析的命令。第二個命令：告訴讓swagger-php\bin\swagger來執行解析命令。第三個命令：告訴swagger-php你要掃描的目錄，只要入口文件在這個目錄下就行。最後一個命令：告訴swagger-php你解析完的命令（就是json文件）寫入到哪裏。這裏生成的json文件也是swagger-ui將要讀取並生成頁面的json。
好了我這裏已經生成了兩個接口cmd裏也能看到。
當然你生成的是什麼也沒有，因爲你什麼也沒有寫。但是界面能夠展示出來了。
第四部
你將自己的接口文件寫在模塊的Controller下即可，就是TP框架怎麼寫你就怎麼寫，但是······註釋必須要按照swagger的規範來。
demo（就是swagger-php文件夾下的）裏邊也有，你也可以看 。規範就是規範必須要按照他的規範來寫。
<?php
namespace app\prettyinterface\controller;
use think\Db;
/**
* @SWG\Tag(
* name="Search",
* description="標籤搜索展示套裝列表"
* )
*/
class SearchController extends FatherController
{
/**
* @SWG\Post(
* path="/Search_Controller/CoordinatesList",
* summary="標籤搜索套裝列表",
* tags={"Search"},
* description="<strong>沒有條件默認展示每頁10條推薦商品。有條件默認展示10件商品。[id:主鍵],[coordinates_id:唯一標識],[image:列表圖片],[price:售價],[comment_count:評價數],[good_comment:好評率],[tag_names:套裝標籤],[up:點贊數],[down:踩數],[recommend:是否推薦0不推薦1推薦]</strong>",
* consumes={ "application/x-www-form-urlencoded"},
* produces={ "application/json"},
* operationId="SearchCoordinatesListPost",
* @SWG\Parameter(
* name="search",
* in="formData",
* description="標籤集合(1，1&2&3)",
* required=false,
* type="string",
* collectionFormat="csv"
* ),
* @SWG\Parameter(
* name="page",
* in="formData",
* description="當前頁碼(默認爲1)",
* required=false,
* type="integer",
* collectionFormat="csv"
* ),
* @SWG\Parameter(
* name="pages",
* in="formData",
* description="每頁顯示數據量(默認爲10)",
* required=false,
* type="integer",
* collectionFormat="csv"
* ),
* @SWG\Response(
* response=200,
* description="josn格式數據<strong>(0請求成功;>0請求有誤;Totle總數據量;Pre_page當前頁碼;Pages每頁數據量)</strong>",
* @SWG\Schema(
* ref="#/definitions/ApiResponse"
* ))
* )
*/
public function CoordinatesList()
{之前入口文件的host拼上basepath在拼上這裏的path正好組成了一個完整的url這樣他才能找到你的後臺接口。想想也不是很神奇。TP5方法名用駝峯需要加下劃線如：Search_Controller。
後注：我這個swagger的介紹也就是比別人詳細一些，而且swagger需要寫這麼麻煩的註釋也省事不到哪裏去呀～SO，我這還有不需要這麼麻煩的註釋也能達到相同的效果，就是自己寫了正則，將普通註釋轉換成了這種繁瑣的swagger認識的註釋
只需寫成這樣：
<?php
namespace app\prettyinterface\controller;
use think\Db;
/**
* @desc 標籤搜索展示套裝列表
* @author 熊童子
*/
class SearchController extends FatherController
{
/**
* @name 標籤搜索套裝列表
* @desc 沒有條件默認展示每頁10條推薦商品。有條件默認展示10件商品。[id:主鍵],[coordinates_id:唯一標識],[image:列表圖片],[price:售價],[comment_count:評價數],[good_comment:好評率],[tag_names:套裝標籤],[up:點贊數],[down:踩數],[recommend:是否推薦0不推薦1推薦]
* @method Post
* @param string search null 標籤集合(1，1&2&3)
* @param integer page null 當前頁碼(默認爲1)
* @param integer pages null 每頁顯示數據量(默認爲10)
* @return josn格式數據
*/
public function CoordinatesList()
{
結果：
