laravel-doc
⛵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中增加了路由文件
访问/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,即可看到效果
链接：https://pan.baidu.com/s/1v5gm7n0L7TGyejCmQrMh2g 提取码：x2p5
免费分享，但是X度限制严重，如若链接失效点击链接或搜索加群 群号518475424。
控制器说明
默认文档的路径
$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
项目为了通用，我并没有提供中间件进行文档和接口的拦截，出于安全考虑，建议使用者可以根据自身需求编写中间件进行文档的保护