laravel api生成接口文档

安装
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
版权声明：著作权归作者所有。商业转载请联系作者获得授权，非商业转载请保留以上作者信息和原文链接。