Laravel 文档工具

laravel-doc

⛵laravel-doc 是一个用来生成文档，经过markdown来撰写文档，并提供web访问文档的项目

项目演示地址

demo.linkgoup.com/

安装要求

• 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

项目为了通用，我并无提供中间件进行文档和接口的拦截，出于安全考虑，建议使用者能够根据自身需求编写中间件进行文档的保护