一鍵產生API文檔
FastAdmin中的一鍵產生API文檔可以在命令列或後台一鍵產生我們API介面的介面測試文檔，可直接在線上模擬介面請求，查看參數範例和返回範例。
準備工作
請確保你的API模組下的控制器程式碼沒有語法錯誤，控制器類別註解、方法名稱註解完整，註解規則請參考下方註解規則
請確保你的FastAdmin已經安裝成功且能正常登入後台
請確保php所在的目錄已經加入到系統環境變量，否則會提示找不到該指令
開啟命令列控制台進入到FastAdmin根目錄，也就是think檔案所在的目錄
常用指令//一鍵產生API文檔
php think api --force=true
//指定https://www.example.com為API介面請求網域名稱,預設為空
php think api -u https://www.example.com --force=true
//輸出自訂檔為myapi.html,預設為api.html
php think api -o myapi.html --force=true
//修改API模板為mytemplate.html，預設為index.html
php think api -e mytemplate.html --force=true
//修改標題為FastAdmin,作者為作者
php think api -t FastAdmin -a Karson --force=true
//查看API介面命令列幫助
php think api -h
參數介紹-u, --url[=URL] 預設API請求URL位址 [default: ""]
-m, --module[=MODULE] 模組名(admin/index/api) [default: "api"]
-o, --output[=OUTPUT] 輸出檔 [default: "api.html"]
-e, --template[=TEMPLATE] 範本檔案 [default: "index.html"]
-f, --force[=FORCE] 覆蓋模式 [default: false]
-t, --title[=TITLE] 文件標題 [default: "FastAdmin"]
-a, --author[=AUTHOR] 文檔作者 [default: "FastAdmin"]
-c, --class[=CLASS] 擴充類別 (multiple values allowed)
-l, --language[=LANGUAGE] 語言 [default: "zh-cn"]
註釋規則
在我們的控制器中通常分為兩部分註釋，一是控制器頭部的註釋，二是控制器方法的註釋。
控制器註解名稱描述範例@ApiSectorAPI分組名稱(測試分組)
@ApiRouteAPI介面URL，此@ApiRoute只是基礎URL(/api/test)
@ApiInternal忽略的控制器,表示此控制將不加入API文件無
@ApiWeighAPI方法的排序,值越大越前(99)
控制器方法註解名稱描述範例@ApiTitleAPI介面的標題,為空時將自動符合註解的文字資訊(測試標題)
@ApiSummaryAPI介面描述(測試描述)
@ApiRouteAPI介面位址,為空時將自動計算請求位址(/api/test/index)
@ApiMethodAPI介面請求方法,預設為GET(POST)
@ApiSectorAPI分組,預設按鈕控制器或控制器的@ApiSector進行分組(測試分組)
@ApiParamsAPI請求參數,如果在@ApiRoute中有對應的{@參數名稱}，將進行替換(name="id", type="integer", required=true, description="會員ID")
@ApiHeadersAPI請求傳遞的Headers資訊(name=token, type=string, required=true, description="請求的Token")
@ApiReturnAPI回傳的結果範例({"code":1,"msg":"回傳成功"})
@ApiReturnParamsAPI回傳的結果參數介紹(name="code", type="integer", required=true, sample="0")
@ApiReturnHeadersAPI回傳的Headers資訊(name="token", type="integer", required=true, sample="123456")
@ApiInternal忽略的方法,表示此方法將不加入文件無
@ApiWeighAPI方法的排序,值越大越前(99)
標準範例<?php
namespace app\api\controller;
/**
* 測試API控制器
*/
class Test extends \app\common\controller\Api
{
// 無需驗證登入的方法
protected $noNeedLogin = ['test'];
// 無需要判斷權限規則的方法
protected $noNeedRight = ['*'];
/**
* 首頁
*
* 可以透過@ApiInternal忽略請求的方法
* @ApiInternal
*/
public function index()
{
return 'index';
}
/**
* 私有方法
* 私有的方法將不會出現在文件列表
*/
private function privatetest()
{
return 'private';
}
/**
* 測試方法
*
* @ApiTitle (測試名稱)
* @ApiSummary (測試描述資訊)
* @ApiSector (測試分組)
* @ApiMethod (POST)
* @ApiRoute (/api/test/test/id/{id}/name/{name})
* @ApiHeaders (name=token, type=string, required=true, description="請求的Token")
* @ApiParams (name="id", type="integer", required=true, description="會員ID")
* @ApiParams (name="name", type="string", required=true, description="使用者名稱")
* @ApiParams (name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string',' age':'integer'}}", description="擴充資料")
* @ApiReturnParams (name="code", type="integer", required=true, sample="0")
* @ApiReturnParams (name="msg", type="string", required=true, sample="回傳成功")
* @ApiReturnParams (name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string',' age':'integer'}}", description="擴充資料回傳")
* @ApiReturn ({
'code':'1',
'mesg':'返回成功'
* })
*/
public function test($id = '', $name = '')
{
$this->success("返回成功", $this->request->request());
}
}
常見問題
如果控制器的方法是private或protected的，則不會產生對應的API文檔
如果註釋不生效，請檢查註釋文字是否正確
