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中添加：
ForyoufengDocDocServiceProvider::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,即可看到效果
控制器說明
默認文檔的路徑
$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
項目為了通用，我并沒有提供中間件進行文檔和接口的攔截，出于安全考慮，建議使用者可以根據自身需求編寫中間件進行文檔的保護
更多Laravel相關技術文章，請訪問Laravel教程欄目進行學習！
