以上是我从网上随便粘贴的一段，虽说本人写代码不是非常洁癖，但这么一大串的注释，本人看着就表示不爽，所以没一点深入了解它的欲望。不介意的就自行研究喽。
优点：同后端代码一起，更新维护距离近在咫尺。
缺点：注释太大块了，感觉影响看功能，代码显得十分拖沓，影响美观。
5.框架内直接编辑markdown文件
这就是我目前最喜欢的方式，也是本文要讲解实现的方式。
优点：同后端代码一起，维护方便；markdown格式编写，文档撰写省时；所有接口在一个页面或几个划分好的页面里，方便浏览和查找。
缺点：要做一些前期工作来实现。但现在有了现成的插件和本文的教程支持，缺点就可以忽略不计了。
以上几种方式都比较完了，现在我就来实现在Laravel内撰写Api文档，支持网页浏览。
要实现的功能主要就是把指定的md文件转换成html。
github上有一个人气很旺的插件：erusev/parsedown, 地址：php解析markdown为html的插件:erusev/parsedown
一般项目涉及PC后台，我这里就新增一个路由文件专门来放这些后台的api。
1.安装erusev/parsedown插件。
编辑composer.json文件，添加代码如下：
"require": {"php": "^7.1.3",
"fideloper/proxy": "^4.0",
"laravel/framework": "5.7.*",
"laravel/tinker": "^1.0",
"erusev/parsedown":"^1.6" //新增的
},
项目根目录下执行composer install进行安装。在vendor文件夹下可看到erusev文件夹，则代表安装成功。
2.在app/Providers/RouteServiceProvider.php中引入自定义的后台路由文件。 public function map(){
$this->mapApiRoutes();
$this->mapWebRoutes();
//新增的后台路由
$this->mapAdminRoutes();
}
protected function mapAdminRoutes()
{
Route::prefix('admin')
// ->middleware('api') //避免篇幅过长，中间件的引入这里就忽略了
->namespace($this->namespace)
->group(base_path('routes/admin.php'));
} 3.添加路由，添加控制器，先调试，要可以成功进入控制器方法。
routes问价下新增admin.php文件，里面加上我们的api文档路由：
Route::get('/apidoc', 'Admin\ApiDocController@showDoc'); //注意后面是反斜杠\,否则会报错laravel框架入口是public/index.php,为了隐藏这个就自定义个本地解析的名称，编辑apache的httpd-vhosts文件如下：
<VirtualHost *:80>ServerName testlaravel
DocumentRoot E:/wamp64/www/laravel/public
<Directory "E:/wamp64/www/laravel/public/">
Options +Indexes +Includes +FollowSymLinks +MultiViews
AllowOverride All
Allow from all
Header set Access-Control-Allow-Origin *
</Directory>
RewriteEngine On
RewriteCond $1 !^(index\.php|images|robots\.txt)
RewriteRule ^(.*)$ /index.php/$1 [L]
</VirtualHost>
编辑好后，重启apache服务。
现在来加控制器，laravel可以用artisan命令生成，方便快捷。在项目根目录执行如下命令：
php artisan make:controller Admin/ApiDocController接下来编辑controller文件：
<?phpnamespace App\Http\Controllers\Admin;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class ApiDocController extends Controller
{
public function showDoc(Request $request){
echo "hello coder";
}
}
浏览器输入,直到出现hello coder后才可以进行后面步骤。
4. 使用插件实现markdown转为html功能很简单，就直接上代码啦。
<?phpnamespace App\Http\Controllers\Admin;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use Parsedown;
class ApiDocController extends Controller
{
public function __construct(){
$this->markdownParser = new Parsedown();
}
public function showDoc(Request $request){
$fileContent = file_get_contents(storage_path('doc/admin_api.md'));
$htmlContent = $this->convertMarkdownToHtml($fileContent);
$content = $this->convertMarkdownToHtml($htmlContent);
return view('apidoc_admin')->with('content',$content);
}
public function convertMarkdownToHtml($markdown)
{
$convertedHmtl = $this->markdownParser->setBreaksEnabled(true)->text($markdown);
return $convertedHmtl;
}
}
本文推荐的就是用markdown编辑api的方式，md就是markdown文件的后缀，我现在把这个文件放在storage/doc/admin_api.md处。