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
項目為了通用，我並沒有提供中間件進行文檔和接口的攔截，出於安全考慮，建議使用者可以根據自身需求編寫中間件進行文檔的保護