API文件 DarkaOnline L5 Swagger套件介紹 - fantasy0107/notes GitHub Wiki
如果你是在Laravel上開發的後端工程師
你想要讓前端工程師知道你開發了那些API並且使用這些API
那麼套件 darkaonline/l5-swagger 會是一個不錯的選擇
這邊有一個範例documentation可以使用看看
安裝 darkaonline/l5-swagger 套件
composer require darkaonline/l5-swagger
建立l5-swagger相關的config和view
php artisan l5-swagger:publish
或
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
這樣自動幫你建立好config和view
設定基本資訊
class Controller extends BaseController
{
use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
/**
* @SWG\Swagger(
* @SWG\Info(
* title="My first swagger documented API",
* version="1.0.0"
* )
* )
*/
}
我會將這個註解寫在 app\Http\Controllers\Controller.php底下
.env設定
L5_SWAGGER_GENERATE_ALWAYS=true
這樣每次載入documentation都會刷新成最新的版本，如果沒有設定的話每次寫完新的都要下
php artisan l5-swagger:generate
才能產生新的文件
API文件預設路徑
localhost/api/documentation
如果想要變更API文件路徑的話可以去config/l5-swagger.php底下routes裡的api進行修改就可以了
接下來產生一個controller
php artisan make:controller Api\UserController --resource
產生Swagger文件
php artisan l5-swagger:generate
Swagger API文件就建立起來了
接下來我會用一個GET的範例來大概要怎麼用
範例 - GET
/**
* @SWG\Get(
* path="/api/users/{id}",
* tags={"user"},
* summary="取得使用者",
* consumes={"application/json"},
* @SWG\Parameter(
* name="Authorization",
* in="header",
* description="token ex:Bearer ed563418549373366792cb00d7e8edbc",
* required=true,
* type="string",
* ),
* @SWG\Parameter(
* name="id",
* in="path",
* required=true,
* type="integer"
* ),
* @SWG\Response(
* response=200,
* description="取得使用者成功",
* examples = {
* "application/json": {
* "id": 10,
* "account": "test3",
* "username": "test3",
* "email": "[email protected]",
* "created_at": "2017-10-16 22:00:03",
* "updated_at": "2017-10-16 22:00:03",
* "last_login_time": "2017-10-16 22:00:03",
* "foo_bar": "Test"
* }
* }
* )
* )
*/
public function show($id)
{
return User::find($id);
}
註解的部分我會寫在相關的controller method上方這樣可以清楚的知道是和哪個method有相關，然後這邊有3個swagger的annotation分別是@SWG\Get, @SWG\Parameter, @SWG\Response下面會稍微介紹一下
consumes={"application/json"}代表會用json格式傳過去
@SWG\Get - HTTP method
是最外層的annotation相關的field或annotation都會寫在這個裡面，然後GET可以換成POST、PUT和DELETE等等
Fields
- path = 設定路徑
- tags = 標籤
- summary = 摘要
- @SWG\Parameter = 參數
- @SWG\Response = 回傳
@SWG\Parameter - 參數
如果想要帶有一些參數可以設定這個annotation
Fields
- name = 參數名稱
- in = 參數位置, 可以是query, path, header, body
- description = 描述
- type= 資料型態
- required = 這個參數是否需要
@SWG\Parameter(
name="id",
in="path",
description="User Id",
required=true,
type="integer"
)
in 可以是path,query,header,body 分別代表的意思
path => /users/{path}
query => /users?query=10
header => HTTP的header
body => HTTP的body
在in = "body"時必須要設定@SWG\Schema這個註解來定義結構的樣子
@SWG\Parameter(
name="body",
in = "body",
description = "List of user object",
required=true,
@SWG\Schema(
type="object",
@SWG\Property(property="id", type="integer", example=1),
@SWG\Property(property="name", type="string", example="Jake")
)
)
@SWG\Response - 回傳
當API成功發送或者失敗可能會有一些訊息回傳可以在這邊設定每個狀態瑪代表的意思和範例
Fields
- response - HTTP狀態碼
- description - 描述
- examples - 例子
@SWG\Response(
response=200,
description="取得使用者成功",
examples = {
"標題": {
"id": 10,
"account": "test3",
"username": "test3",
"email": "[email protected]",
"created_at": "2017-10-16 22:00:03",
"updated_at": "2017-10-16 22:00:03",
"last_login_time": "2017-10-16 22:00:03",
"foo_bar": "Test"
}
}
)
這邊是說當回傳的HTTP狀態碼為200時代表我取的特定的使用者成功了而且回傳格式為id, account, username....
@SWG\Definition
有的時候你可能會想要重複使用Model，這時只要用@SWG\Definition並設定title和@SWG\Property給予預設值後就可以重複使用了
/**
* @SWG\Definition(
* title="User",
* @SWG\Property(property="id", type="integer", example=1),
* @SWG\Property(property="account", type="integer", example="account"),
* @SWG\Property(property="password", type="integer", example="password"),
* @SWG\Property(property="username", type="integer", example="Jake")
* )
*/
class User extends Authenticatable
{
...
}
這樣之後都可以在@SWG\Response中使用
@SWG\Response(
response=200,
description="取得使用者成功",
@SWG\Schema(
ref="#/definitions/User"
)
)
其它
property object - array
* @SWG\Property(
* property="tags",
* type="array",
* @SWG\Items(type="string", example={"A", "C", "C"})
* ),
array 沒有 key
@SWG\Property(
property="numbers",
example={10, 20}
)
上傳檔案
consumes={"multipart/form-data"}
@SWG\Parameter(
name = "file",
in= "formData",
type = "file",
description= "圖片上傳",
required= false,
)
範本
/**
* 刪除循序漸進暫存設定
*
* @SWG\Delete(
* path="",
* tags={""},
* summary="",
* consumes={"application/json"},
* @SWG\Parameter(
* name="Authorization",
* in="header",
* description="token ex:Bearer ed563418549373366792cb00d7e8edbc",
* required=true,
* type="string",
* ),
* @SWG\Response(
* response=200,
* description="",
* @SWG\Schema(
* @SWG\Property(
* property="result",
* type="string",
* example="success"
* ),
* @SWG\Property(
* property="data",
* type="object",
* ref="#/definitions/CirclenewModeNotok"
* ),
* @SWG\Property(
* property="debug",
* type="array",
* @SWG\Items()
* )
* )
* )
* )
*/
參數設定
* @SWG\Parameter(
* name="A",
* in="header",
* description="10",
* required=true,
* type="string",
*),
回傳陣列
* @SWG\Response(
* response=200,
* description="成功",
* @SWG\Schema(
* type="array",
* @SWG\Items(
* ref="#/definitions/Rule"
* )
* )
* )
參考資料
DarkaOnLine/L5-Swagger Github
swagger-php Github
Generate beautiful RESTful Laravel API documentation with Swagger
OpenAPI Specification 2.0