laravel-doc

⛵laravel-doc is a project that generates documents, writes documents through Markdown, and provides Web access to documents

Project Demo Address

demo.linkgoup.com/

Installation requirements

  • PHP > = 7.0.0
  • Laravel >= 5

Documents screenshots

Interface screenshots

The installation

 composer require foryoufeng/laravel-doc
Copy the code

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


 Foryoufeng\Doc\DocServiceProvider::class


Copy the code

Run the following command to publish the resource file


 php artisan doc:install

Copy the code

There are many more files after publishing resources

/public/vendor/laravel-doc // style file /resources/ docs // interface file /resources/ MDS /docs // documentation file /resources/ MDS /apidocs // API file Http / / app/Controllers/Docs / / increased controller config files/laravel_doc PHP configuration file routes / / document/web. PHP increased the routing fileCopy the code

access/doc, you can see the documentation for this project

access/apidoc, you can see the interface documentation for this project

How to use

General documentation

In MDS/resources/docs to create your md file, such as demo, md, add what you need, and then to Http/app/Controllers/docs/LaravelDocController PHP index_md add data access, Such as:

// 2 examples private have been added by defaultfunction 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',]]; }Copy the code

Then visit /doc to see the effect

Controller Description

Path to the default document

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

The code inside getMenu() is the menu displayed in the document, which is used to write the document

  • Configure multiple menu examples
protected function getMenu()
    return[['name'=>config('laravel_doc.languages.project_doc'),
                    'spread'= >true// Whether the menu is expanded,falseDo not open'children'= > ['name'=>config('laravel_doc.languages.install'),
                            'doc_link'= >'install.md',]], ['name'=>config('laravel_doc.languages.project_doc'),
                    'spread'= >false// Do not expand the menu'children'= > ['name'=>config('laravel_doc.languages.install'),
                            'doc_link'= >'install.md',]]]; }Copy the code
  • After the configuration of the menu can be inresources/mds/docsIn the newdoc_link, and then write the document

API interface documentation

Create your md file in resources/ MDS /apidocs, such as demo.md, and add what you need, Then to Http/app/Controllers/Docs/LaravelApiDocController PHP index_md add data can access, such as:

private function index_md()
    {
        return[['name'= >'apidoc_html'.'doc_link'= >'apidoc_html.md', // Can modify your own$this->host to use your own access address'url'= >$this->host.'apidoc/html'.'request_type'= >'get'// Request mode GET or POST // Request parameters'params'= > ['name'= >'apidoc_html.md',]], ['name'= >'demo'.'doc_link'= >'demo.md'.'url'= >$this->host.'apidoc/html'.'request_type'= >'get'// Request mode get or POST // Give some parameters to request'params'= > ['name'= >' '.'user_id'= >' ',]]]; }Copy the code

Then visit /apidoc to see the effect

Click on the provided demo:apidoc_html to see the request path and required request parameters above, as well as the parameter documentation below

Click the Send request button to execute the Ajax request, and if the interface is fine, ajax data will be returned. At this point, clicking generate Document will open a Markdown edit box and a rendering on the right. The interface will retrieve the request path, parameters, and return values defined in the current click page. $this->mds_path = $this->mds_path = $this->mds_path = $this->mds_path You configure doc_link, such as: the resources/MDS/apidocs/demo. Md, to generate the file

laravel_doc.phpConfiguration File Description

/ / laravel - the name of the doc'name'= >'Laravel-doc', // used to define the name of the writer interface'author' => env('DOC_AUTHOR'.'foryoufeng'// The interface request sends the token'token' => env('DOC_TOKEN'.'doc'), // can be used for internationalization'languages'= > ['search'= >'search'.'search_result'= >'Search Results'.'project_doc'= >'Project Documentation'.'doc_name'= >'Document name'.'install'= >'install'.'how_use'= >'Instructions'.'request_type'= >'HTTP request mode'.'request_url'= >'Requested address'.'send_request'= >'Send request'.'generate_doc'= >'Generate document'.'welcome_use'= >'Welcome'.'param'= >'parameters'.'value'= >'value'.'generate'= >'generation',]Copy the code

The advanced

  • Multiple projects

If your project is small and you only have one document and one API document, In Http/app/Controllers/Docs/LaravelApiDocController PHP and Http/app/Controllers/Docs/LaravelDocController PHP Adding your documents to the web should basically meet the requirements

If there are multiple projects, can copy Http/app/Controllers/Docs, resources/views/Docs, can in the resources/MDS/directory in your new directory to write the document Then defined in the routing file need routing, need to copy the following these routing

//doc route
Route::group(['namespace'= >'Docs'].function (){
    Route::get('doc'.'LaravelDocController@index')->name('doc.index'); //md file returns to HTML Route::get('doc/html'.'LaravelDocController@html')->name('doc.html');
    Route::get('apidoc'.'LaravelApiDocController@index')->name('doc.apidoc'); //md file returns to HTML Route::get('apidoc/html'.'LaravelApiDocController@html')->name('doc.apidoc.html'); // Preview API documentation Route::post('apidoc/markdown'.'LaravelApiDocController@markdown')->name('doc.apidoc.markdown'); Route::post('apidoc/save'.'LaravelApiDocController@save')->name('doc.apidoc.save');

});
Copy the code

  • internationalization

You can change languages in config/laravel_doc.php to Chinese by default

  • The interface interceptor

In config/laravel_doc.php, there is a token configuration. When the interface makes ajax requests, it carries an Access-token in the header. According to this configuration, the interface can perform middleware processing, such as obtaining user information by using the specified token. Interface requests, assignments, etc

  • tips

For general purpose, I did not provide middleware to intercept documents and interfaces. For security reasons, I suggest users write middleware to protect documents according to their own requirements