Laravel 文檔工具

時間 2019-12-01

標籤 laravel 文檔工具简体版

原文原文鏈接

laravel-doc

⛵laravel-doc 是一個用來生成文檔，經過markdown來撰寫文檔，並提供web訪問文檔的項目php

項目演示地址

demo.linkgoup.com/html

安裝要求

PHP >= 7.0.0
Laravel >= 5

文檔截圖laravel

接口截圖web

安裝

composer require foryoufeng/laravel-doc
複製代碼

若是你是運行的Laravel 5.5如下的版本，須要在config/app.php的service provider中添加：ajax

Foryoufeng\Doc\DocServiceProvider::class


複製代碼

運行以下命令來發布資源文件api

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中加入數據便可訪問，例如：bash

//默認已經加入了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,便可看到效果markdown

控制器說明

默認文檔的路徑app

$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');

});
複製代碼