swagger簡介
swagger搭建過程
swagger主要分為兩個部分，swagger-ui和swagger-php，ui用於展示，后者用於生成相關api。
首先，在自己項目的合理位置上下載前端ui和生成的php。放在項目里面是為了保證訪問地址和咱們接口地址都在一起，不會是訪問時產生跨域問題。
swagger-ui：https://github.com/swagger-api/swagger-ui.git
swagger-php：https://github.com/zircote/swagger-php.git
第一步：ui搭建
在ui里面有個dist文件夾，修改文件夾里面index.html文件，將url里的位置寫成自己的項目地址
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://XXXX/doc/swagger.json";
}
hljs.configure({
highlightSizeThreshold: 5000
});
到此位置我們的ui已經配置完了。
第二步：生成環境搭建
下載swagger-php后，進入此文件夾，使用composer下載swagger-php下載swagger-php所需要的依賴，使用命令行，輸入（前提是安裝了composer）：
composer update
這樣后台就算完成了搭建，我們的swagger-php多了vender文件夾
第三步：代碼注解
在我們的controller models的文件中編寫注解
控制器注釋
/**
* @SWG\Get(path="/user/login", 請求路徑
* tags={"user"}, 標簽
* summary="用戶登錄", 概要
* description="用戶手機號登錄", 描述
* operationId="loginUser", 此ID必須在API中描述的所有操作中是唯一的
* produces={"application/xml", "application/json"},
* @SWG\Parameter( 參數列表
* name="mobile", 參數名
* in="query", 1表單參數 formData 2查詢參數 query 3路徑參數 path 4頭參數 header
* description="用戶的手機號", 描述
* default="137********", 默認值
* required=false, 是否必填
* type="string" 數據類型
* ),
* @SWG\Parameter(
* name="code",
* in="query",
* description="用戶的手機號驗證碼",
* default="456789",
* required=false,
* type="string"
* ),
* @SWG\Response( 返回狀態
* response=200,
* description="成功",
* @SWG\Schema(type="string"),
* @SWG\Header(
* header="X-Rate-Limit",
* type="integer",
* format="int32",
* description="calls per hour allowed by the user"
* ),
* @SWG\Header(
* header="X-Expires-After",
* type="string",
* format="date-time",
* description="date in UTC when toekn expires"
* )
* ),
* @SWG\Response(response=400, description="Invalid username/password supplied")
* )
*/
模型注釋
/**
* @SWG\Definition(@SWG\Xml(name="User")) 屬性定義
*/
class User
{
/**
* @SWG\Property(format="int64")
* @var int
*/
public $id;
/**
* @SWG\Property()
* @var string
*/
public $username;
/**
* @var string
* @SWG\Property()
*/
public $password;
/**
* @var string
* @SWG\Property()
*/
public $phone;
}
更多了解查看 http://bfanger.github.io/swagger-explained/#/parameterObject
第四步：文檔生成
第三步也是最重要的一步，生成相關api，生成方式十分簡單，只需要在命令行里執行命令
php swagge-php/bin/swagger 接口文件夾 -o 生成的目的文件夾
"-o" 前面代表API源目錄, 即你想要生成哪個目錄的API文檔, 你的項目代碼目錄. "-o" 后面是生成到哪個path
目的文件夾建議寫在項目文件夾下，也是為了避免跨域問題。
每次改動API代碼注釋之后都要手動生成json文件? 太麻煩了, 寫了個controller, 每次訪問swagger-ui的這個controller
$swagger = \Swagger\scan('../app'); api路徑
$json_file = "../vendor/zircote/swagger-docs/swagger.json";
$ss=file_put_contents($json_file, $swagger);
Methods
HTTP協議提供了很多methods來操作數據：
-
GET: 獲取某個資源。
-
POST: 創建一個新的資源。
-
PUT: 替換某個已有的資源。
-
DELETE：刪除某個資源。
request Headers
-
Accept：服務器需要返回什么樣的content
-
If-Modified-Since/If-None-Match：如果客戶端提供某個條件，那么當這條件滿足時，才返回數據，否則返回304 not modified。比如客戶端已經緩存了某個數據，它只是想看看有沒有新的數據時，會用這兩個header之一，服務器如果不理不睬，依舊做足全套功課，返回200 ok，那就既不專業，也不高效了。
-
If-Match：在對某個資源做PUT/DELETE操作時，服務器應該要求客戶端提供If-Match頭，只有客戶端提供的Etag與服務器對應資源的Etag一致，才進行操作，否則返回412 precondition failed。
Response Headers
- date：消息發送的時間
- server：包含處理請求的原始服務器的軟件信息
- content-type ：接收方指示實體的介質類型
- expires：緩存過期時間
Status Codes
- 200 OK - [GET]：服務器成功返回用戶請求的數據。
- 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
- 202 Accepted - [*]：表示一個請求已經進入后台排隊（異步任務）
- 204 NO CONTENT - [DELETE]：用戶刪除數據成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作。
- 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
- 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
- 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作。
- 406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
- 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。
- 500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。