Laravel

Laravel 문서화 도구

步履不停

Jul 03, 2019 pm 02:33 PM

laravel

Laravel 문서화 도구

laravel-doc

⛵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.php的index_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.php的index_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.php和app/Http/Controllers/Docs/LaravelDocController.php
中加入你的文档应该基本满足要求

如果有多个项目，可以复制app/Http/Controllers/Docs、resources/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

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

설치 요구 사항

PHP >= 7.0.0

Laravel >= 5

Installation

rrreeeLaravel 5.5 미만 버전을 실행하는 경우 다음이 필요합니다. config/app.php의 서비스 공급자 추가: rrreee

다음 명령을 실행하여 리소스 파일을 게시하세요🎜rrreee🎜리소스를 게시한 후에는 더 많은 파일이 있을 것입니다🎜rrreee🎜 방문 /doc, 이 프로젝트의 문서를 볼 수 있습니다🎜🎜<code>/apidoc를 방문하면 이 프로젝트의 인터페이스 문서를 볼 수 있습니다🎜🎜사용 방법🎜

일반 문서 작성

h2>🎜demo.md와 같은 resources/mds/docs에 md 파일을 만들고 필요한 콘텐츠를 추가한 다음
로 이동하여 app/Http/Controllers/Docs/LaravelDocController.php의 index_md에 데이터를 추가하여 액세스하세요. 예: 🎜rrreee🎜 그런 다음 /doc 효과 보기🎜🎜컨트롤러 설명🎜🎜기본 문서 경로🎜rrreee🎜<code>getMenu()안의 코드는 문서에 표시되는 메뉴로, 문서 작성에 필요한 메뉴입니다🎜

여러 메뉴 구성 예제rrreee
메뉴를 구성한 후 resources/mds/docsdoc_link

에 지정된 새 md 파일을 생성할 수 있습니다. code>를 선택한 후 문서 작성

API 인터페이스 문서 작성

🎜resources/mds/apidocs에 md 파일을 생성하세요. demo.md와 같은 필요한 콘텐츠를 추가한 다음
app/Http/Controllers/Docs/LaravelApiDocController.php의 <code>index_md로 이동하세요. 액세스할 데이터를 추가하세요. 예: 🎜rrreee🎜 그런 다음 /apidoc를 방문하여 효과를 확인하세요.🎜🎜제공된 데모를 클릭하세요. apidoc_html를 클릭하여 위 내용을 확인하세요. 요청 경로와 필수 요청 매개변수 그리고 아래 매개변수 문서🎜🎜요청 보내기 버튼을 클릭하면 ajax 요청이 실행됩니다. 인터페이스에 문제가 없으면 ajax 데이터가 반환됩니다.
이때 문서 생성을 클릭하면 markdown 편집 상자와 오른쪽 렌더링이 열립니다. 이 인터페이스는 현재 클릭한 페이지
, 반환 값 등. 미리보기 효과에서 인터페이스 사람, 매개변수 설명을 수정하여 각 매개변수를 설명할 수 있습니다.
반환 값에 대한 설명 등을 입력합니다. 그런 다음 생성 버튼을 클릭하면 정의한 $this->mds_path를 기반으로 합니다.
resources/mds/apidocs/demo.md와 같이 구성하여 파일🎜

🎜laravel_doc.php을 생성합니다. > 구성 파일 설명🎜rrreee🎜Advanced🎜

여러 프로젝트
🎜프로젝트가 상대적으로 작고 하나의 문서와 하나의 API 인터페이스 문서만 작성하면 되는 경우 app/Http/Controllers/Docs/LaravelApiDocController.php 및 app/Http/Controllers/Docs/LaravelDocController.php
는 기본적으로 요구 사항을 충족해야 합니다🎜 li>

🎜여러 프로젝트가 있는 경우 app/Http/Controllers/Docs, resources/views/docs를 복사하고 새 프로젝트를 만들 수 있습니다. 문서를 작성하려는 resources/mds/ 디렉터리에
그런 다음 라우팅 파일에 필요한 경로를 정의해야 합니다.🎜rrreee

국제화
🎜config/laravel_doc.php언어를 수정하여 언어를 변경할 수 있습니다. 기본값은 중국어🎜
인터페이스 차단
🎜in config /laravel_doc.php에 token 구성이 있습니다. 인터페이스가 Ajax 요청을 할 때. , 액세스 토큰은 헤더에 포함됩니다. 인터페이스는
이 구성을 기반으로 미들웨어 프로세스를 수행할 수 있습니다. 지정된 토큰을 사용하여 해당 사용자 정보를 얻고 인터페이스 요청 및 할당을 수행할 수 있습니다. 프로젝트의 보편화를 위해 문서와 인터페이스를 가로채는 미들웨어를 제공하지 않았습니다. 보안상의 이유로 사용자가 문서를 보호하기 위해 필요에 따라 미들웨어를 작성하는 것이 좋습니다.🎜🎜Laravel 관련 자세한 내용은 기술 관련 기사를 보려면 🎜Laravel Tutorial🎜 칼럼을 방문하세요! 🎜