经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置：技术经验 » 程序设计 » PHP » 查看文章
Laravel文档工具 - it-world
来源：cnblogs　　作者：it-world　　时间：2019/10/31 9:01:42　　对本文有异议

laravel-doc

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

安装要求

  • PHP >= 7.0.0
  • Laravel >= 5

安装

  1. composer require foryoufeng/laravel-doc

 

   

如果你是运行的Laravel 5.5以下的版本，需要在config/app.php的service provider中添加：

  1. Foryoufeng\Doc\DocServiceProvider::class

 

   

运行如下命令来发布资源文件

  1. php artisan doc:install

 

   

发布资源之后会多出很多文件

  1. /public/vendor/laravel-doc  //样式文件
  2.  
  3.  
  4.  
  5. /resources/views/docs   //界面文件
  6.  
  7.  
  8.  
  9. /resources/mds/docs  //文档文件
  10.  
  11.  
  12.  
  13. /resources/mds/apidocs  //api文件
  14.  
  15.  
  16.  
  17. /app/Http/Controllers/Docs  //增加了控制器文件
  18.  
  19.  
  20.  
  21. config/laravel_doc.php  //文档配置文件
  22.  
  23.  
  24.  
  25. routes/web.php中增加了路由文件

 

   

访问/doc,即可看到本项目的说明文档

访问/apidoc,即可看到本项目的接口说明文档

如何使用

普通文档的编写

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

  1. //默认已经加入了2个例子
  2.  
  3. private function index_md()
  4.  
  5.     {
  6.  
  7.         return  [
  8.  
  9.             [
  10.  
  11.                 'name' => config('laravel_doc.languages.install'),
  12.  
  13.                 'doc_link' => 'install.md',
  14.  
  15.             ],
  16.  
  17.             [
  18.  
  19.                 'name' => config('laravel_doc.languages.how_use'),
  20.  
  21.                 'doc_link' => 'how_use.md',
  22.  
  23.             ],
  24.  
  25.             [
  26.  
  27.                 'name' => 'demo',
  28.  
  29.                 'doc_link' => 'demo.md',
  30.  
  31.             ],
  32.  
  33.         ];
  34.  
  35.     }

 

   

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

控制器说明

默认文档的路径

  1. $this->mds_path=resource_path('mds/docs/');

 

   

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

  • 配置多个菜单示例
    1. protected function getMenu()
    2.  
    3. return [
    4.  
    5.             [
    6.  
    7.                 'name'=>config('laravel_doc.languages.project_doc'),
    8.  
    9.                 'spread'=>true,//菜单是否展开，false不展开
    10.  
    11.                 'children'=>[
    12.  
    13.                         'name'=>config('laravel_doc.languages.install'),
    14.  
    15.                         'doc_link'=>'install.md',
    16.  
    17.                      ],
    18.  
    19.             ],
    20.  
    21.             [
    22.  
    23.                 'name'=>config('laravel_doc.languages.project_doc'),
    24.  
    25.                 'spread'=>false,//不展开菜单
    26.  
    27.                 'children'=>[
    28.  
    29.                         'name'=>config('laravel_doc.languages.install'),
    30.  
    31.                         'doc_link'=>'install.md',
    32.  
    33.                  ],
    34.  
    35.             ],
    36.  
    37.         ];
    38.  
    39. }

     

  • 配置好菜单后可以在resources/mds/docs中新建doc_link中指定的md文件，然后进行文档的编写

api接口文档的编写

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

  1. private function index_md()
  2.  
  3.     {
  4.  
  5.         return  [
  6.  
  7.             [
  8.  
  9.                 'name' => 'apidoc_html',
  10.  
  11.                 'doc_link' => 'apidoc_html.md',
  12.  
  13.                 //可自行修改你的$this->host来使用你自己定义的访问地址
  14.  
  15.                 'url' => $this->host.'apidoc/html',
  16.  
  17.                 'request_type' => 'get',//请求方式 get或者post
  18.  
  19.                 //请求参数
  20.  
  21.                 'params'=>[
  22.  
  23.                     'name'=>'apidoc_html.md',
  24.  
  25.                 ]
  26.  
  27.             ],
  28.  
  29.             [
  30.  
  31.                 'name' => 'demo',
  32.  
  33.                 'doc_link' => 'demo.md',
  34.  
  35.                 'url' => $this->host.'apidoc/html',
  36.  
  37.                 'request_type' => 'get',//请求方式 get或者post
  38.  
  39.                 //给定一些需要请求的参数
  40.  
  41.                 'params'=>[
  42.  
  43.                     'name'=>'',
  44.  
  45.                     'user_id'=>'',
  46.  
  47.                 ]
  48.  
  49.             ],
  50.  
  51.         ];
  52.  
  53.     }

 

   

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

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

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

laravel_doc.php 配置文件说明

  1. //laravel-doc的名字
  2.  
  3. 'name' => 'Laravel-doc',
  4.  
  5. //用在了定义撰写接口人的名字
  6.  
  7. 'author' => env('DOC_AUTHOR','foryoufeng'),
  8.  
  9. //接口请求发送了这个token
  10.  
  11. 'token' => env('DOC_TOKEN','doc'),
  12.  
  13. //做国际化时可以用到
  14.  
  15. 'languages'=>[
  16.  
  17.     'search'=>'搜索',
  18.  
  19.     'search_result'=>'搜索结果',
  20.  
  21.     'project_doc'=>'项目文档',
  22.  
  23.     'doc_name'=>'文档名称',
  24.  
  25.     'install'=>'安装',
  26.  
  27.     'how_use'=>'使用说明',
  28.  
  29.     'request_type'=>'http请求方式',
  30.  
  31.     'request_url'=>'请求地址',
  32.  
  33.     'send_request'=>'发送请求',
  34.  
  35.     'generate_doc'=>'生成文档',
  36.  
  37.     'welcome_use'=>'欢迎使用',
  38.  
  39.     'param'=>'参数',
  40.  
  41.     'value'=>'值',
  42.  
  43.     'generate'=>'生成',
  44.  
  45. ]

 

   

进阶

  • 多项目

    如果你的项目比较小，只用写一个文档和一个api接口文档，那么在app/Http/Controllers/Docs/LaravelApiDocController.php和app/Http/Controllers/Docs/LaravelDocController.php
    中加入你的文档应该基本满足要求

如果有多个项目，可以复制app/Http/Controllers/Docs、resources/views/docs,可以在resources/mds/目录中新建你准备写文档的目录
然后在路由文件中定义好需要的路由，需要复制下面的这些路由

  1. //doc route
  2.  
  3. Route::group(['namespace'=>'Docs'],function (){
  4.  
  5.     Route::get('doc', 'LaravelDocController@index')->name('doc.index');
  6.  
  7.     //md文件返回到html
  8.  
  9.     Route::get('doc/html', 'LaravelDocController@html')->name('doc.html');
  10.  
  11.     Route::get('apidoc', 'LaravelApiDocController@index')->name('doc.apidoc');
  12.  
  13.     //md文件返回到html
  14.  
  15.     Route::get('apidoc/html', 'LaravelApiDocController@html')->name('doc.apidoc.html');
  16.  
  17.     //预览api文档
  18.  
  19.     Route::post('apidoc/markdown', 'LaravelApiDocController@markdown')->name('doc.apidoc.markdown');
  20.  
  21.     //生成api文档
  22.  
  23.     Route::post('apidoc/save', 'LaravelApiDocController@save')->name('doc.apidoc.save');
  24.  
  25.  
  26.  
  27. });

 

   

  • 国际化

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

  • 接口拦截

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

  • tips

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

原文链接：http://www.cnblogs.com/it-3327/p/11765110.html

 友情链接：直通硅谷 　点职佳 　北美留学生论坛

PHP热门文章

  • 收藏了8年的PHP优秀资源，都给你整理好了
  • php对微信支付回调处理的方法（合集）
  • 聊聊TCP连接耗时的那些事儿
  • php如何比较两个浮点数是否相等详解
  • PHP实现PDO操作mysql存储过程示例
  • 富文本编辑器新增导入word功能，自动转为html，可直接显示图片
  • curl put方式上传文件
  • thinkphp3.2模块名如何不区分大小写?
  • php去掉字符串的最后一个字符
  • WebSocket 长连接 及超时问题解决

    • PHP推荐文章

  • 【workerman】uniapp+thinkPHP5使用GatewayWorker实现实时通讯
  • PHP转Go系列 | ThinkPHP与Gin框架之API接口签名设计实践
  • MagicArray:像php一样，让Go业务代码不再卷！
  • 2023年的PHP项目部署笔记。什么？还有人用PHP？
  • [CTF/Web] PHP 反序列化学习笔记
  • PHP的序列化和反序列化入门
  • 详解PHP实现HTTP服务器过程
  • 高效率开发Web安全扫描器之路（一）
  • PHP实现微信扫码登录功能的两种方式总结
  • PHP内存溢出的解决方法详解

    • 本站QQ群：前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

    W3xue 的所有内容仅供测试，对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
    关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接（目前9元/月）请联系QQ：27243702 沸活量
    皖ICP备17017327号-2　皖公网安备34020702000426号