Laravel 安装 l5-swagger 扩展 让项目支持 Swagger

背景
用 Laravel 作为 API 支持框架，如果能够在写代码的过程，随便就把文档写了，那么是不是感觉很方便呢。

安装过程
当前操作默认在项目 根目录：

使用 composer 添加该包

composer require darkaonline/l5-swagger
生成配置文件到 config 目录，可以自行去看看其中配置项

php artisan vendor:publish –provider “L5Swagger\L5SwaggerServiceProvider”
跑起来

php artisan serve
Laravel development server started: http://127.0.0.1:8000
浏览器访问
浏览器打开：http://127.0.0.1:8000/api/documentation

安装完毕

具体使用
刚接触它时候，我是拒绝的，总想用已知的东西来否认逃避去了解它，为什么不用 postman 呢？当出现这个想法的时候，我变成了 锤子，面对所有的问题 都把它 想成 钉子，咬牙看完 swagger 文档后，才知： 锤子+1 。

L5-Swagger 是什么？
是 laravel 的一个扩展包，结合 swagger-php + swagger-ui , 使我们能够在编写代码的时候，通过编写注释，生成 API 接口文档，并且可直接在开发的项目上直接访问这些 API 接口。

第一步：编写可生成 API 文档的注释
解析注释生成 API 文档的的功臣是 swagger-php，所以要安照它的使用方法来，它的 github 地址是：swagger-php 下面的内容假设在你已经了解了 swagger 的相关语法。

如：

<?php

/**

• @SWG\Info(title=”Test”, version=”0.0.1″)
  */
  // 别直接复制这里的注释，缩进破坏了，
  // 请上 github 上复制它的用例。这里只作为演示作用

class MyController
{

/**

• @SWG\Get(
• path=”/api/syahi”,
• @SWG\Response(response=”200″, description=”An example resource”)
• )
  */
  public function say()
  {
  return [‘msg’ => ‘Hello World’];
  }
  // Other Code…
  }
  注意 我用的版本是 swagger-php 2.x，所以注释使用的是 @SWG，现在最新版本使用的是 @OA 做为标识（OpenApi 首字母）。

想了解更多，可以上 github, 到该项目的演示项目参考其它注释方法:Examples

第二步：生成 API 文档
编写完上面的注释，运行此命名：

php artisan l5-swagger:generate
它会生成 API 文档，默认在项目根目录： storage\api-docs\api-docs.json，如：

第三步：浏览器访问

当然可以配置自动生成 API 文档，请自行到 L5-Swagger 取经！

后话
本文只是做一个入门的指引，解决最基本的问题：跑起来。
本人是在接触 swagger 不到 24 小时内，要求项目中使用它，文章肯定有不足的地方，请各位谅解！
现在接触下来，发现 swagger 很方便。
见与你有缘，有一篇： 如何编写基于 Swagger-PHP 的 API 文档 能助你轻松掌握 swager-php！