在laravel中集成swagger

swagger是非常好用的一个API文档工具，大大地减轻了前端和后端的沟通成本。在写后端接口的时候，也可以用它来测试接口，非常方便。 整个过程如下。

新建一个laravel项目

composer create-project --prefer-dist laravel/laravel Blog

集成Swagger

获取darkaonline/l5-swagger

composer require "darkaonline/l5-swagger"

注册组件

在config/app.php的providers中添加\L5Swagger\L5SwaggerServiceProvider::class,

创建swagger-UI等

php artisan l5-swagger:publish

创建swagger配置文件

php artisan l5-swagger:publish-config

执行该命令后，会在config目录下产生一个l5-swagger.php的配置文件，里面包含了swagger标题，token验证，路由等。 其中’generate_always’配置可以根据需要修改下，它表示是否每次都刷新swagger。如果是关闭，则修改swagger配置后，要使用php artisan l5-swagger:generate命令手动刷新。

访问测试

在浏览器访问http://127.0.0.1/api/documentation,可以看到swagger的界面了，但会提示缺少api-docs.json文件。 可以在app下创建个php文件，如swagger.php，内容如下

<?php /** * Class Controller * * @package App\Http\Controllers * * @SWG\Swagger( * basePath="", * host="127.0.0.1", * schemes={"http"}, * @SWG\Info( * version="1.0", * title="OpenApi", * @SWG\Contact(name="Pek Ratanak", url="https://www.google.com"), * ), * @SWG\Definition( * definition="Error", * required={"code", "message"}, * @SWG\Property( * property="code", * type="integer", * format="int32" * ), * @SWG\Property( * property="message", * type="string" * ) * ) * ) */

刷新下swagger，重新访问

php artisan l5-swagger:generate

添加测试API

比如创建一个test的TestController php artisan make:controller TestController 内容如下

<?php namespace App\Http\Controllers; use Illuminate\Http\Request; class TestController extends Controller { /** * @SWG\Get( * path="/api/test", * description="返回测试内容", * operationId="api.dashboard.index", * produces={"application/json"}, * tags={"测试"}, * @SWG\Parameter( * in="formData", * name="reason", * type="string", * description="拿数据的理由", * required=true, * ), * @SWG\Response( * response=200, * description="Dashboard overview." * ), * @SWG\Response( * response=401, * description="Unauthorized action.", * ) * ) */ public function index(Request $request) { return response()->json([ 'result' => [ 'statistics' => [ 'users' => [ 'name' => 'Name', 'email' => 'user@example.com' ] ], ], 'message' => '', 'type' => 'success', 'status' => 0 ]); } }

添加下路由

Route::get('test', 'TestController@index');

最终效果如下

参考 Integrate Swagger API documentation with Laravel Project (L5 Swagger)