Laravel文檔工具

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,即可看到效果

控制器說明

預設文檔的路徑

$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教學

專欄進行學習！

以上是Laravel文檔工具的詳細內容。更多資訊請關注PHP中文網其他相關文章！