安装
composer require foryoufeng/laravel-doc
如果报错:
composer更新报错问题Carbon 1 is deprecated, see how to migrate to Carbon 2
这个报错的大概意思是:nesbot/carbon 这个扩展包将要被废弃,建议我们升级到 carbon-2,但是carbon-2 要求 Laravel 的最低版本是5.8。但是我用的是Laravel5.5,而且是线上项目,不能随便升级,对于这种情况,官方也给出了方案,解决方案如下。
在 composer.json 文件 require 部分,添加以下两行:
“kylekatarnls/laravel-carbon-2”: “^1.0.0”,
“nesbot/carbon”: “2.16.3 as 1.34.0”
修改完之后,再次执行composer update就可以了。
如果你是运行的 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’);
});
————————————————
原文作者:foryoufeng
转自链接:https://learnku.com/articles/30607
版权声明:著作权归作者所有。商业转载请联系作者获得授权,非商业转载请保留以上作者信息和原文链接。