目录
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脱衣机

Video Face Swap

Video Face Swap

使用我们完全免费的人工智能换脸工具轻松在任何视频中换脸!

热工具

记事本++7.3.1

记事本++7.3.1

好用且免费的代码编辑器

SublimeText3汉化版

SublimeText3汉化版

中文版,非常好用

禅工作室 13.0.1

禅工作室 13.0.1

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

Dreamweaver CS6

Dreamweaver CS6

视觉化网页开发工具

SublimeText3 Mac版

SublimeText3 Mac版

神级代码编辑软件(SublimeText3)

在Laravel中如何获取邮件发送失败时的退信代码? 在Laravel中如何获取邮件发送失败时的退信代码? Apr 01, 2025 pm 02:45 PM

Laravel邮件发送失败时的退信代码获取方法在使用Laravel开发应用时,经常会遇到需要发送验证码的情况。而在实�...

Laravel计划任务不执行:schedule:run命令后任务未运行怎么办? Laravel计划任务不执行:schedule:run命令后任务未运行怎么办? Mar 31, 2025 pm 11:24 PM

Laravel计划任务运行无响应排查在使用Laravel的计划任务调度时,不少开发者会遇到这样的问题:schedule:run...

在 Laravel 中,如何处理邮件发送验证码失败的情况? 在 Laravel 中,如何处理邮件发送验证码失败的情况? Mar 31, 2025 pm 11:48 PM

Laravel邮件发送验证码失败时的处理方法在使用Laravel...

在dcat admin中如何实现点击添加数据的自定义表格功能? 在dcat admin中如何实现点击添加数据的自定义表格功能? Apr 01, 2025 am 07:09 AM

在dcatadmin(laravel-admin)中如何实现自定义点击添加数据的表格功能在使用dcat...

Laravel - 转储服务器 Laravel - 转储服务器 Aug 27, 2024 am 10:51 AM

Laravel - 转储服务器 - Laravel 转储服务器随 Laravel 5.7 版本一起提供。以前的版本不包括任何转储服务器。转储服务器将成为 laravel/laravel Composer 文件中的开发依赖项。

Laravel Redis连接共享:为何select方法会影响其他连接? Laravel Redis连接共享:为何select方法会影响其他连接? Apr 01, 2025 am 07:45 AM

Laravel框架中Redis连接的共享与select方法的影响在使用Laravel框架和Redis时,开发者可能会遇到一个问题:通过配置...

Laravel多租户扩展stancl/tenancy:如何自定义租户数据库连接的主机地址? Laravel多租户扩展stancl/tenancy:如何自定义租户数据库连接的主机地址? Apr 01, 2025 am 09:09 AM

在Laravel多租户扩展包stancl/tenancy中自定义租户数据库连接使用Laravel多租户扩展包stancl/tenancy构建多租户应用时,...

Laravel - 操作 URL Laravel - 操作 URL Aug 27, 2024 am 10:51 AM

Laravel - Action URL - Laravel 5.7 引入了一项名为“可调用操作 URL”的新功能。此功能类似于 Laravel 5.6 中的功能,即在操作方法中接受字符串。 Laravel 5.7 引入新语法的主要目的是直接

See all articles