Laravel文档工具
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
,即可看到效果
控制器说明
默认文档的路径
$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
项目为了通用,我并没有提供中间件进行文档和接口的拦截,出于安全考虑,建议使用者可以根据自身需求编写中间件进行文档的保护
更多Laravel相关技术文章,请访问Laravel教程栏目进行学习!
以上是Laravel文档工具的详细内容。更多信息请关注PHP中文网其他相关文章!

热AI工具

Undresser.AI Undress
人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover
用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool
免费脱衣服图片

Clothoff.io
AI脱衣机

AI Hentai Generator
免费生成ai无尽的。

热门文章

热工具

记事本++7.3.1
好用且免费的代码编辑器

SublimeText3汉化版
中文版,非常好用

禅工作室 13.0.1
功能强大的PHP集成开发环境

Dreamweaver CS6
视觉化网页开发工具

SublimeText3 Mac版
神级代码编辑软件(SublimeText3)

PHP和Flutter是移动端开发的流行技术。Flutter胜在跨平台能力、性能和用户界面,适合需要高性能、跨平台和自定义UI的应用程序。PHP则适用于性能较低、不跨平台的服务器端应用程序。

使用ORM可简化PHP中的数据库操作,它将对象映射到关系数据库中。Laravel中的EloquentORM允许使用面向对象的语法与数据库交互,可通过定义模型类、使用Eloquent方法或在实战中构建博客系统等方式来使用ORM。

PHP单元测试工具分析:PHPUnit:适用于大型项目,提供全面功能,易于安装,但可能冗长且速度较慢。PHPUnitWrapper:适合小型项目,易于使用,针对Lumen/Laravel优化,但功能受限,不提供代码覆盖率分析,社区支持有限。

Laravel - Artisan 命令 - Laravel 5.7 提供了处理和测试新命令的新方法。它包括测试 artisan 命令的新功能,下面提到了演示?

Laravel9和CodeIgniter4的最新版本提供了更新的特性和改进。Laravel9采用MVC架构,提供数据库迁移、身份验证和模板引擎等功能。CodeIgniter4采用HMVC架构,提供路由、ORM和缓存。在性能方面,Laravel9的基于服务提供者设计模式和CodeIgniter4的轻量级框架使其具有出色的性能。在实际应用中,Laravel9适用于需要灵活性和强大功能的复杂项目,而CodeIgniter4适用于快速开发和小型应用程序。

比较Laravel和CodeIgniter的数据处理能力:ORM:Laravel使用EloquentORM,提供类对象关系映射,而CodeIgniter使用ActiveRecord,将数据库模型表示为PHP类的子类。查询构建器:Laravel具有灵活的链式查询API,而CodeIgniter的查询构建器更简单,基于数组。数据验证:Laravel提供了一个Validator类,支持自定义验证规则,而CodeIgniter的验证功能内置较少,需要手动编码自定义规则。实战案例:用户注册示例展示了Lar

PHP单元和集成测试指南单元测试:关注单个代码单元或函数,使用PHPUnit创建测试用例类进行验证。集成测试:关注多个代码单元协同工作的情况,使用PHPUnit的setUp()和tearDown()方法设置和清理测试环境。实战案例:使用PHPUnit在Laravel应用中进行单元和集成测试,包括创建数据库、启动服务器以及编写测试代码。

在选择大型项目框架时,Laravel和CodeIgniter各有优势。Laravel针对企业级应用程序而设计,提供模块化设计、依赖项注入和强大的功能集。CodeIgniter是一款轻量级框架,更适合小型到中型项目,强调速度和易用性。对于具有复杂需求和大量用户的大型项目,Laravel的强大功能和可扩展性更合适。而对于简单项目或资源有限的情况下,CodeIgniter的轻量级和快速开发能力则更为理想。
