Laravel文档工具

⛵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中增加了路由文件

普通文档的编写

在resources/mds/docs中创建你的md文件,如demo.md,加入你需要的内容，
然后到app/Http/Controllers/Docs/LaravelDocController.php的index_md中加入数据即可访问，例如：

//默认已经加入了2个例子
private function index_md()
    {
        return  [
            [
                &＃39;name&＃39; => config(&＃39;laravel_doc.languages.install&＃39;),
                &＃39;doc_link&＃39; => &＃39;install.md&＃39;,
            ],
            [
                &＃39;name&＃39; => config(&＃39;laravel_doc.languages.how_use&＃39;),
                &＃39;doc_link&＃39; => &＃39;how_use.md&＃39;,
            ],
            [
                &＃39;name&＃39; => &＃39;demo&＃39;,
                &＃39;doc_link&＃39; => &＃39;demo.md&＃39;,
            ],
        ];
    }

然后访问/doc,即可看到效果

默认文档的路径

$this->mds_path=resource_path(&＃39;mds/docs/&＃39;);

getMenu()里面的代码是文档显示的菜单,这个是写文档需要用到的

• 配置多个菜单示例

  protected function getMenu()
  return [
              [
                  &＃39;name&＃39;=>config(&＃39;laravel_doc.languages.project_doc&＃39;),
                  &＃39;spread&＃39;=>true,//菜单是否展开，false不展开
                  &＃39;children&＃39;=>[
                          &＃39;name&＃39;=>config(&＃39;laravel_doc.languages.install&＃39;),
                          &＃39;doc_link&＃39;=>&＃39;install.md&＃39;,
                       ],
              ],
              [
                  &＃39;name&＃39;=>config(&＃39;laravel_doc.languages.project_doc&＃39;),
                  &＃39;spread&＃39;=>false,//不展开菜单
                  &＃39;children&＃39;=>[
                          &＃39;name&＃39;=>config(&＃39;laravel_doc.languages.install&＃39;),
                          &＃39;doc_link&＃39;=>&＃39;install.md&＃39;,
                   ],
              ],
          ];
  }

• 配置好菜单后可以在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  [
            [
                &＃39;name&＃39; => &＃39;apidoc_html&＃39;,
                &＃39;doc_link&＃39; => &＃39;apidoc_html.md&＃39;,
                //可自行修改你的$this->host来使用你自己定义的访问地址
                &＃39;url&＃39; => $this->host.&＃39;apidoc/html&＃39;,
                &＃39;request_type&＃39; => &＃39;get&＃39;,//请求方式 get或者post
                //请求参数
                &＃39;params&＃39;=>[
                    &＃39;name&＃39;=>&＃39;apidoc_html.md&＃39;,
                ]
            ],
            [
                &＃39;name&＃39; => &＃39;demo&＃39;,
                &＃39;doc_link&＃39; => &＃39;demo.md&＃39;,
                &＃39;url&＃39; => $this->host.&＃39;apidoc/html&＃39;,
                &＃39;request_type&＃39; => &＃39;get&＃39;,//请求方式 get或者post
                //给定一些需要请求的参数
                &＃39;params&＃39;=>[
                    &＃39;name&＃39;=>&＃39;&＃39;,
                    &＃39;user_id&＃39;=>&＃39;&＃39;,
                ]
            ],
        ];
    }

然后访问/apidoc,即可看到效果

点击提供的demo:apidoc_html,即可看到上面的请求路径和需要的请求参数，以及下面的参数文档

点击发送请求按钮，可以执行ajax请求，如果接口没有问题的话，就会返回ajax数据了
这个时候点击生成文档，会打开一个markdown的编辑框和右侧的效果图，该界面获取了当前点击页面
中定义的请求路径，参数，返回值等，在预览效果中你可以修改接口人，参数说明中对每个参数进行说明，
以及返回值的说明等，然后点击生成按钮，会根据你定义的$this->mds_path.你配置的doc_link，
如：resources/mds/apidocs/demo.md，来产生文件

    //laravel-doc的名字
    &＃39;name&＃39; => &＃39;Laravel-doc&＃39;,
    //用在了定义撰写接口人的名字
    &＃39;author&＃39; => env(&＃39;DOC_AUTHOR&＃39;,&＃39;foryoufeng&＃39;),
    //接口请求发送了这个token
    &＃39;token&＃39; => env(&＃39;DOC_TOKEN&＃39;,&＃39;doc&＃39;),
    //做国际化时可以用到
    &＃39;languages&＃39;=>[
        &＃39;search&＃39;=>&＃39;搜索&＃39;,
        &＃39;search_result&＃39;=>&＃39;搜索结果&＃39;,
        &＃39;project_doc&＃39;=>&＃39;项目文档&＃39;,
        &＃39;doc_name&＃39;=>&＃39;文档名称&＃39;,
        &＃39;install&＃39;=>&＃39;安装&＃39;,
        &＃39;how_use&＃39;=>&＃39;使用说明&＃39;,
        &＃39;request_type&＃39;=>&＃39;http请求方式&＃39;,
        &＃39;request_url&＃39;=>&＃39;请求地址&＃39;,
        &＃39;send_request&＃39;=>&＃39;发送请求&＃39;,
        &＃39;generate_doc&＃39;=>&＃39;生成文档&＃39;,
        &＃39;welcome_use&＃39;=>&＃39;欢迎使用&＃39;,
        &＃39;param&＃39;=>&＃39;参数&＃39;,
        &＃39;value&＃39;=>&＃39;值&＃39;,
        &＃39;generate&＃39;=>&＃39;生成&＃39;,
    ]

• 多项目

  如果你的项目比较小，只用写一个文档和一个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([&＃39;namespace&＃39;=>&＃39;Docs&＃39;],function (){
    Route::get(&＃39;doc&＃39;, &＃39;LaravelDocController@index&＃39;)->name(&＃39;doc.index&＃39;);
    //md文件返回到html
    Route::get(&＃39;doc/html&＃39;, &＃39;LaravelDocController@html&＃39;)->name(&＃39;doc.html&＃39;);
    Route::get(&＃39;apidoc&＃39;, &＃39;LaravelApiDocController@index&＃39;)->name(&＃39;doc.apidoc&＃39;);
    //md文件返回到html
    Route::get(&＃39;apidoc/html&＃39;, &＃39;LaravelApiDocController@html&＃39;)->name(&＃39;doc.apidoc.html&＃39;);
    //预览api文档
    Route::post(&＃39;apidoc/markdown&＃39;, &＃39;LaravelApiDocController@markdown&＃39;)->name(&＃39;doc.apidoc.markdown&＃39;);
    //生成api文档
    Route::post(&＃39;apidoc/save&＃39;, &＃39;LaravelApiDocController@save&＃39;)->name(&＃39;doc.apidoc.save&＃39;);

});

• 国际化

  可以修改config/laravel_doc.php中的languages来更换语言，默认提供的是中文

• 接口拦截

  在config/laravel_doc.php中有一个token的配置，接口做ajax请求时在header中带了Access-Token,接口可以根据这个配置，
  做一个中间件的处理，比如使用指定的token就可以获取对应用户的信息，进行接口的请求和赋值等

• tips

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

更多Laravel相关技术文章，请访问Laravel教程栏目进行学习！

以上就是Laravel文档工具的详细内容，更多请关注其它相关文章！