laravel-doc

⛵laravel-doc は、ドキュメントの生成、マークダウンによるドキュメントの作成、ドキュメントへの Web アクセスの提供に使用されるツールです。プロジェクト

インストール要件

PHP >= 7.0.0
Laravel >= 5

インストール

 composer require foryoufeng/laravel-doc

ログイン後にコピー

Laravel 5.5 以前を実行している場合は、config/app.php にサービスプロバイダーを追加する必要があります:

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

ログイン後にコピー

Visit `/doc`、このプロジェクトのドキュメントを参照できます

Visit `/apidoc` では、このプロジェクトのインターフェイス説明ドキュメントが表示されます。

使用方法

一般的なドキュメントの作成

resources/mds/docs# にあります。 ##demo.md などの md ファイルを作成し、必要なコンテンツを追加して、app/Http/Controllers/Docs/LaravelDocController.php# の に移動します。 ## データを index_md
に追加してアクセスします。例: <div class="code" style="position:relative; padding:0px; margin:0px;"><pre class="brush:php;toolbar:false">//默认已经加入了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', ], ]; }</pre><div class="contentsignin">ログイン後にコピー</div></div> 次に、/doc にアクセスして効果を確認します。

コントローラーの説明デフォルトのドキュメントパス

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

ログイン後にコピー

getMenu()

内部のコードはドキュメントに表示されるメニューです。これはドキュメントの作成に必要なものです。

複数のメニューの構成例<div class="code" style="position:relative; padding:0px; margin:0px;"><pre class="brush:php;toolbar:false">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', ], ], ]; }</pre><div class="contentsignin">ログイン後にコピー</div></div>

メニューを構成した後、

の
で指定された新しい md ファイルを作成し、ドキュメントを書き込むことができますAPI インターフェイスドキュメントの作成

resources/mds/apidocs

に

demo.md

などの md ファイルを作成します。必要なコンテンツを追加します。 次に、アクセスするために app/Http/Controllers/Docs/LaravelApiDocController.php の index_md
にデータを追加します。例: <div class="code" style="position:relative; padding:0px; margin:0px;"><pre class="brush:php;toolbar:false">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'=>'', ] ], ]; }</pre><div class="contentsignin">ログイン後にコピー</div></div>その後、/apidoc にアクセスすると、その効果がわかります。

提供されたデモ:apidoc_html をクリックすると、上記のリクエストが表示されますパスと必要なリクエストパラメータ、および次のパラメータドキュメント

Send request ボタンをクリックして ajax リクエストを実行すると、インターフェースに問題がなければ、ajax データが返されます。

このとき、

をクリックしてドキュメント を生成すると、markdown
の編集ボックスが表示され、右側のレンダリングが開き、リクエストのパス、パラメータ、戻り値を取得するインターフェースです。、現在クリックされているページ で定義されているものなど、プレビュー効果で Interface Person、Parameter description
を変更して、各パラメータ、、および戻り値の説明を説明できます。などを入力して、Generate ボタンをクリックすると、定義した $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'=>'生成',
    ]

ログイン後にコピー

上級

複数のプロジェクト

プロジェクトが比較的小規模で、1 つのドキュメントと 1 つの API インターフェイスドキュメントのみを作成する必要がある場合は、

および
app/Http/Controllers/Docs ドキュメントを /LaravelDocController.php

に追加すると、基本的に要件を満たしているはずです #複数のプロジェクトがある場合は、
app/Http/Controllers/Docs
,

をコピーし、

resources/mds に新しいディレクトリを作成できます/ ドキュメントを作成する予定のディレクトリ を作成し、ルーティングファイルに必要なルートを定義します。次のルートをコピーする必要があります<div class="code" style="position:relative; padding:0px; margin:0px;"><pre class="brush:php;toolbar:false">//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'); });</pre><div class="contentsignin">ログイン後にコピー</div></div>Internationalization

の
langages
を変更できます。言語を変更します。デフォルトは
中国語 です。インターフェイスインターセプト
##token
設定に#があり、インターフェイスがAjaxリクエストを行うと、
Access-Token
が含まれますheader インターフェイスは、この設定に基づいて middle を作成できます。たとえば、指定された token を使用してファイル を処理すると、次のように取得できます。対応するユーザー情報の取得、インターフェイスのリクエストと割り当ての実行など。
ヒント
Laravel 関連の技術記事の詳細については、## を参照してください。 #Laravel チュートリアル