基于Laravel构建API文档扩展Swagger

介绍：

    Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。（简单来说就是构建Annotation） 

    首先使用composer安装swagger-php扩展包

    $ composer require zircote/swagger-php    

    创建一个laravel控制器

 php artisan make:controller SwaggerController 

    在控制器中写入两个方法（分别是getJson  getData）

namespace    App\Http\Controllers;

useIlluminate\Http\Request;

useApp\Http\Requests;

useApp\Http\Controllers\Controller;

classSwaggerControllerextendsController{

/**

    * 返回JSON格式的Swagger定义

    */

public function getJSON(){    }

/**

    * 假设是项目中的一个API

    */

public function getData(){    }}

配置相应路由

Route::group(['prefix' => 'swagger'], function () {

Route::get('json', 'SwaggerController@getJSON');

Route::get('my-data', 'SwaggerController@getMyData');

})

我们先实现getJSON方法，使其能够返回合法的Swagger定义：

// ... /** * 返回JSON格式的Swagger定义

* * 这里需要一个主`Swagger`定义：

* @SWG\Swagger( * @SWG\Info(

* title="我的`Swagger`API文档",

* version="1.0.0"

* )

* )

*/

public function getJSON() {

// 你可以将API的`Swagger Annotation`写在实现API的代码旁，从而方便维护， // `swagger-php`会扫描你定义的目录，自动合并所有定义。这里我们直接用`Controller/` // 文件夹。

$swagger = \Swagger\scan(app_path('Http/Controllers/')); return response()->json($swagger, 200); }

// ...

访问一下/swagger/json，如果我们看到下面的返回就说明搭建成功了：

{"swagger":"2.0","info":{"title":"\u6211\u7684`Swagger`API\u6587\u6863","version":"1.0.0"},"paths":{},"definitions":{}}