目录
laravel-doc
安装要求
安装
访问/doc,即可看到本项目的说明文档
访问/apidoc,即可看到本项目的接口说明文档
如何使用
普通文档的编写
控制器说明
api接口文档的编写
进阶
多项目
国际化
接口拦截
首页 php框架 Laravel Laravel文档工具

Laravel文档工具

Jul 03, 2019 pm 02:33 PM
laravel

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.phpindex_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.phpindex_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.phpapp/Http/Controllers/Docs/LaravelDocController.php
    中加入你的文档应该基本满足要求

如果有多个项目,可以复制app/Http/Controllers/Docsresources/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中文网其他相关文章!

本站声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

热AI工具

Undresser.AI Undress

Undresser.AI Undress

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

AI Clothes Remover

AI Clothes Remover

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

Undress AI Tool

Undress AI Tool

免费脱衣服图片

Clothoff.io

Clothoff.io

AI脱衣机

AI Hentai Generator

AI Hentai Generator

免费生成ai无尽的。

热门文章

R.E.P.O.能量晶体解释及其做什么(黄色晶体)
2 周前 By 尊渡假赌尊渡假赌尊渡假赌
仓库:如何复兴队友
4 周前 By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island冒险:如何获得巨型种子
4 周前 By 尊渡假赌尊渡假赌尊渡假赌

热工具

记事本++7.3.1

记事本++7.3.1

好用且免费的代码编辑器

SublimeText3汉化版

SublimeText3汉化版

中文版,非常好用

禅工作室 13.0.1

禅工作室 13.0.1

功能强大的PHP集成开发环境

Dreamweaver CS6

Dreamweaver CS6

视觉化网页开发工具

SublimeText3 Mac版

SublimeText3 Mac版

神级代码编辑软件(SublimeText3)

PHP 与 Flutter 的比较:移动端开发的最佳选择 PHP 与 Flutter 的比较:移动端开发的最佳选择 May 06, 2024 pm 10:45 PM

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

PHP中如何使用对象-关系映射(ORM)简化数据库操作? PHP中如何使用对象-关系映射(ORM)简化数据库操作? May 07, 2024 am 08:39 AM

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

PHP 单元测试工具的优缺点分析 PHP 单元测试工具的优缺点分析 May 06, 2024 pm 10:51 PM

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

Laravel - Artisan 命令 Laravel - Artisan 命令 Aug 27, 2024 am 10:51 AM

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

Laravel和CodeIgniter的最新版本对比 Laravel和CodeIgniter的最新版本对比 Jun 05, 2024 pm 05:29 PM

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

Laravel 和 CodeIgniter 中数据处理能力的比较如何? Laravel 和 CodeIgniter 中数据处理能力的比较如何? Jun 01, 2024 pm 01:34 PM

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

PHP 代码单元测试与集成测试 PHP 代码单元测试与集成测试 May 07, 2024 am 08:00 AM

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

Laravel和CodeIgniter:哪种框架更适合大型项目? Laravel和CodeIgniter:哪种框架更适合大型项目? Jun 04, 2024 am 09:09 AM

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

See all articles