Laravel Documentation Tool

laravel-doc

⛵laravel-doc is a tool used to generate documents, write documents through markdown, and provide web access to documents Project

Installation Requirements

• PHP >= 7.0.0
• Laravel >= 5

Installation

 composer require foryoufeng/laravel-doc

If you are running Laravel 5.5 or below, you need to add the service provider in config/app.php:

 Foryoufeng\Doc\DocServiceProvider::class

Run the following command to publish the resource file

 php artisan doc:install

After publishing resources, there will be many more files

/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中增加了路由文件

Visit /doc, you can see the documentation of this project

Visit/apidoc , you can see the interface description document of this project

How to use

Common document writing

In resources/mds/docs Create your md file, such as demo.md, add the content you need,
then go to of app/Http/Controllers/Docs/LaravelDocController.php Add data to index_md to access it, for example:

//默认已经加入了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',
            ],
        ];
    }

Then visit /doc to see the effect

Controller description

Default document path

$this->mds_path=resource_path('mds/docs/');

getMenu()The code inside is the menu displayed in the document. This is what is needed to write the document.

• Configure multiple Menu example

  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',
                   ],
              ],
          ];
  }

• After configuring the menu, you can create a new md file specified in doc_link in resources/mds/docs, and then write the document

---

Writing of api interface document

Create your md file in resources/mds/apidocs, such as demo.md, and add it The content you need,
Then add data to index_md in app/Http/Controllers/Docs/LaravelApiDocController.php to access it, for example:

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'=>'',
                ]
            ],
        ];
    }

Then visit /apidoc, and you can see the effect.

Click on the provided demo:apidoc_html, and you can see the above request path and required request parameters. And the following parameter document

Click the Send request button to execute the ajax request. If there is no problem with the interface, the ajax data will be returned.
At this time, click to generate the document , an edit box of markdown and the rendering on the right will open. This interface obtains the request path, parameters, return value, etc. defined in the currently clicked page
, in the preview effect You can modify Interface Person, Parameter Description to describe each parameter,
and return value description, etc., and then click the Generate button, it will According to the $this->mds_path you defined. The doc_link you configured,
such as: resources/mds/apidocs/demo.md, to Generate file

---

laravel_doc.php Configuration file description

    //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'=>'生成',
    ]

Advanced

• ##Multiple projects
  If your project is relatively small and you only need to write one document and one api interface document, then in

  app/Http/Controllers/Docs/LaravelApiDocController.php and app/Http/Controllers/Docs Adding your documents to /LaravelDocController.php should basically meet the requirements
  

If you have multiple projects, you can copy

app/Http/Controllers/Docs, resources/views/docs, you can create a new directory in the resources/mds/ directory where you plan to write documents and then define the required routes in the routing file. You need to copy the following routes

//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');

});

• Internationalization
  You can modify

  languages in config/laravel_doc.php Change the language, the default is Chinese

• Interface interception
  There is a# in

  config/laravel_doc.php ##token configuration, when the interface makes an ajax request, Access-Token is included in header. The interface can make a middle based on this configuration. Processing of file
  , for example, using the specified token, you can obtain the corresponding user information, perform interface requests and assignments, etc.

tips

For the sake of universal project, I did not provide middleware to intercept documents and interfaces. For security reasons, it is recommended that users can write middleware according to their own needs to protect documents

For more Laravel related technical articles, please visit the

Laravel Tutorial

column to learn!

The above is the detailed content of Laravel Documentation Tool. For more information, please follow other related articles on the PHP Chinese website!