laravel-doc
?laravel-doc 是一個用來生成檔案，通過markdown來撰寫檔案，并提供web訪問檔案的專案
安裝要求
- PHP >= 7.0.0
- Laravel >= 5
安裝
composer require foryoufeng/laravel-doc
如果你是運行的Laravel 5.5以下的版本，需要在config/app.php的service provider中添加：
Foryoufeng\Doc\DocServiceProvider::class
運行如下命令來發布資源檔案
php artisan doc:install
發布資源之后會多出很多檔案
/public/vendor/laravel-doc //樣式檔案 /resources/views/docs //界面檔案 /resources/mds/docs //檔案檔案 /resources/mds/apidocs //api檔案 /app/Http/Controllers/Docs //增加了控制器檔案 config/laravel_doc.php //檔案組態檔 routes/web.php中增加了路由檔案
訪問/doc,即可看到本專案的說明檔案
訪問/apidoc,即可看到本專案的介面說明檔案
如何使用
普通檔案的撰寫
在resources/mds/docs中創建你的md檔案,如demo.md,加入你需要的內容，
然后到app/Http/Controllers/Docs/LaravelDocController.php的index_md中加入資料即可訪問，例如：
//默認已經加入了2個例子
private function index_md()
{
return [
[
'name' => config('laravel_doc.languages.install'),
'doc_link' => 'install.md',
],
[
'name' => config('laravel_doc.languages.how_use'),
'doc_link' => 'how_use.md',
],
[
'name' => 'demo',
'doc_link' => 'demo.md',
],
];
}
然后訪問/doc,即可看到效果
鏈接：https://pan.baidu.com/s/1v5gm7n0L7TGyejCmQrMh2g 提取碼：x2p5
免費分享，但是X度限制嚴重，如若鏈接失效點擊鏈接或搜索加群 群號518475424，
控制器說明
默認檔案的路徑
$this->mds_path=resource_path('mds/docs/');
getMenu()里面的代碼是檔案顯示的選單,這個是寫檔案需要用到的
- 配置多個選單示例
-
protected function getMenu() return [ [ 'name'=>config('laravel_doc.languages.project_doc'), 'spread'=>true,//選單是否展開，false不展開 'children'=>[ 'name'=>config('laravel_doc.languages.install'), 'doc_link'=>'install.md', ], ], [ 'name'=>config('laravel_doc.languages.project_doc'), 'spread'=>false,//不展開選單 'children'=>[ 'name'=>config('laravel_doc.languages.install'), 'doc_link'=>'install.md', ], ], ]; } - 配置好選單后可以在
resources/mds/docs中新建doc_link中指定的md檔案，然后進行檔案的撰寫
api介面檔案的撰寫
在resources/mds/apidocs中創建你的md檔案,如demo.md,加入你需要的內容，
然后到app/Http/Controllers/Docs/LaravelApiDocController.php的index_md中加入資料即可訪問，例如：
private function index_md()
{
return [
[
'name' => 'apidoc_html',
'doc_link' => 'apidoc_html.md',
//可自行修改你的$this->host來使用你自己定義的訪問地址
'url' => $this->host.'apidoc/html',
'request_type' => 'get',//請求方式 get或者post
//請求引數
'params'=>[
'name'=>'apidoc_html.md',
]
],
[
'name' => 'demo',
'doc_link' => 'demo.md',
'url' => $this->host.'apidoc/html',
'request_type' => 'get',//請求方式 get或者post
//給定一些需要請求的引數
'params'=>[
'name'=>'',
'user_id'=>'',
]
],
];
}
然后訪問/apidoc,即可看到效果
點擊提供的demo:apidoc_html,即可看到上面的請求路徑和需要的請求引數，以及下面的引數檔案
點擊發送請求按鈕，可以執行ajax請求，如果介面沒有問題的話，就會回傳ajax資料了
這個時候點擊生成檔案，會打開一個markdown的編輯框和右側的效果圖，該界面獲取了當前點擊頁面
中定義的請求路徑，引數，回傳值等，在預覽效果中你可以修改介面人，引數說明中對每個引數進行說明，
以及回傳值的說明等，然后點擊生成按鈕，會根據你定義的$this->mds_path.你配置的doc_link，
如：resources/mds/apidocs/demo.md，來產生檔案
laravel_doc.php 組態檔說明
//laravel-doc的名字
'name' => 'Laravel-doc',
//用在了定義撰寫介面人的名字
'author' => env('DOC_AUTHOR','foryoufeng'),
//介面請求發送了這個token
'token' => env('DOC_TOKEN','doc'),
//做國際化時可以用到
'languages'=>[
'search'=>'搜索',
'search_result'=>'搜索結果',
'project_doc'=>'專案檔案',
'doc_name'=>'檔案名稱',
'install'=>'安裝',
'how_use'=>'使用說明',
'request_type'=>'http請求方式',
'request_url'=>'請求地址',
'send_request'=>'發送請求',
'generate_doc'=>'生成檔案',
'welcome_use'=>'歡迎使用',
'param'=>'引數',
'value'=>'值',
'generate'=>'生成',
]
進階
-
多專案
如果你的專案比較小，只用寫一個檔案和一個api介面檔案，那么在
app/Http/Controllers/Docs/LaravelApiDocController.php和app/Http/Controllers/Docs/LaravelDocController.php
中加入你的檔案應該基本滿足要求
如果有多個專案，可以復制app/Http/Controllers/Docs、resources/views/docs,可以在resources/mds/目錄中新建你準備寫檔案的目錄
然后在路由檔案中定義好需要的路由，需要復制下面的這些路由
//doc route
Route::group(['namespace'=>'Docs'],function (){
Route::get('doc', 'LaravelDocController@index')->name('doc.index');
//md檔案回傳到html
Route::get('doc/html', 'LaravelDocController@html')->name('doc.html');
Route::get('apidoc', 'LaravelApiDocController@index')->name('doc.apidoc');
//md檔案回傳到html
Route::get('apidoc/html', 'LaravelApiDocController@html')->name('doc.apidoc.html');
//預覽api檔案
Route::post('apidoc/markdown', 'LaravelApiDocController@markdown')->name('doc.apidoc.markdown');
//生成api檔案
Route::post('apidoc/save', 'LaravelApiDocController@save')->name('doc.apidoc.save');
});
-
國際化
可以修改
config/laravel_doc.php中的languages來更換語言，默認提供的是中文 -
介面攔截
在
config/laravel_doc.php中有一個token的配置，介面做ajax請求時在header中帶了Access-Token,介面可以根據這個配置，
做一個中間件的處理，比如使用指定的token就可以獲取對應用戶的資訊，進行介面的請求和賦值等 -
tips
專案為了通用，我并沒有提供中間件進行檔案和介面的攔截，出于安全考慮，建議使用者可以根據自身需求撰寫中間件進行檔案的保護
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/125437.html
標籤：PHP
下一篇：ndarray物件屬性