Outil de documentation Laravel

laravel-doc

⛵laravel-doc est un projet utilisé pour générer des documents, rédiger des documents via markdown et fournir un accès Web aux documents

Conditions d'installation

• PHP >= 7.0.0
• Laravel >= 5

Installation

 composer require foryoufeng/laravel-doc

Si vous êtes Si vous utilisez Laravel 5.5 ou une version antérieure, vous devez ajouter le fournisseur de services de config/app.php :

 Foryoufeng\Doc\DocServiceProvider::class

Exécutez la commande suivante pour publier le fichier de ressources

 php artisan doc:install

Après avoir publié la ressource, il y a il y aura beaucoup plus de fichiers

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

Visitez /doc, vous pouvez voir la documentation de ce projet

Visitez /apidoc, vous pouvez voir la documentation de l'interface de ce projet

Comment utiliser

Rédaction de documents communs

Créez votre fichier md dans resources/mds/docs, tel que demo.md, ajoutez le contenu dont vous avez besoin,
puis ajoutez-le à app/Http/Controllers/Docs/LaravelDocController.php dans index_md Les données sont accessibles, par exemple :

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

Puis accédez à /doc pour voir l'effet

Description du contrôleur

Chemin du document par défaut

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

getMenu()Le code à l'intérieur est le menu affiché dans le document, qui est nécessaire pour écrire le document

• Configuration de plusieurs exemples de menu

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

• Après avoir configuré le menu, vous peut resources/mds/docsCréer le fichier md spécifié dans doc_link, puis écrire le document

---

Écrire le document d'interface API

Créer votre fichier md dans resources/mds/apidocs , comme demo.md, ajoutez le contenu dont vous avez besoin,
puis ajoutez des données à app/Http/Controllers/Docs/LaravelApiDocController.php de index_md pour y accéder, par exemple :

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

puis accédez à /apidoc pour voir Effet

Cliquez sur la démo fournie :apidoc_html pour voir le chemin de la requête ci-dessus et les paramètres de requête requis, ainsi que le document de paramètres suivant

Cliquez sur le bouton 发送请求 pour exécuter la requête ajax, s'il n'y a pas de problème avec l'interface, les données ajax seront renvoyées
A ce moment, cliquez sur 生成文档, et une zone d'édition de markdown et un rendu à droite s'ouvriront. Cette interface obtient la page actuellement cliquée.
Le chemin de la requête, les paramètres, la valeur de retour, etc. définis dans , vous pouvez modifier 接口人 dans l'effet d'aperçu, expliquer chaque paramètre dans 参数说明,
et la description de la valeur de retour, etc., puis cliquez sur le bouton 生成, générera le fichier $this->mds_pathdoc_link
resources/mds/apidocs/demo.md description du fichier de configuration

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

---

Avancé

laravel_doc.php

Multi- projet

Si votre projet est relativement petit et que vous n'avez besoin d'écrire qu'un seul document et un document d'interface API, alors dans
• et

  Les documents que vous ajoutez

  devraient essentiellement répondre aux exigences

  app/Http/Controllers/Docs/LaravelApiDocController.phpapp/Http/Controllers/Docs/LaravelDocController.php
  Si vous avez plusieurs projets, vous pouvez copier

  ,
, et en créer un nouveau dans le répertoire

pour votre préparation Écrivez le répertoire du document

puis définissez les itinéraires requis dans le fichier de routage Vous devez copier les itinéraires suivants app/Http/Controllers/Docs

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

});

resources/views/docsresources/mds/
Internationalisation

peut être modifié

• dans <.> pour changer la langue. La valeur par défaut fournie est

  config/laravel_doc.phplanguages中文Interception de l'interface

Il y a une configuration
• dans

  , interface Lors de la création d'un Requête ajax,

  est inclus dans

  . L'interface peut utiliser cette configuration pour effectuer un traitement config/laravel_doc.php sur token. Par exemple, en utilisant le header spécifié, vous pouvez obtenir les informations utilisateur correspondantes et exécuter l'interface. traitement. Demandes et missions, etc. Access-Token
中间件tokenconseils

Pour plus d'articles techniques liés à Laravel, veuillez visitez la colonne

Apprenez dans la colonne Tutoriel Laravel 项目为了通用，我并没有提供中间件进行文档和接口的拦截，出于安全考虑，建议使用者可以根据自身需求编写中间件进行文档的保护 !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!