laravel+swagger运用

第一步：安装swagger-php依赖包;

composer require 'zircote/swagger-php:2.*'

注意:这里要求用2.*版本好兼容下面的swagger语句，如果用3.*版本，不保证兼容代码

第二步：生成swagger-json文档;

建立swaggerController控制器，用于生成json文档

<?php

namespace App\Http\Controllers;

class SwaggerController extends Controller
{
    /**
     * @SWG\Swagger(
     *     schemes={"http","https"},
     *     host="",
     *     basePath="/",
     *     @SWG\Info(
     *         version="1.0.0",
     *         title="this is title",
     *         description="Api description...",
     *         termsOfService="",
     *     ),
     * )
     */

    public function getJSON()
    {
        // 正式环境(production)访问swagger文档时返回空
        if (config('app.env') == 'production') {
            return response()->json([], 200);
        }

        $swagger = \Swagger\scan(app_path('/'));

        return response()->json($swagger, 200);
    }
}

第三步：定义路由;

在web.php里写上生成json文档的路由

//swagger
Route::group(['prefix'=>'doc'],function(){
    Route::get('json','SwaggerController@getJson');  //获取swagger.json
});

此时json文档接口地址为：

http://你的域名/doc/json

第四步：下载swagger-ui;

1, 下载地址 https://github.com/swagger-api/swagger-ui;

2, 将dist里的文件拷贝到项目根目录swagger里面;

3, 修改swagger/index.html里的url地址为:

url: "/doc/json",

4, 访问：

http://你的域名/swagger

即可看到生成的swagger文档页面了

第五步：写swagger注释;

任意找一个接口，写上swagger注释，这个地方需要注意swagger语法，这里有两个案例，post和get;

Post接口案例:

/**
     * @SWG\Post(
     *     path="/api/auth/login",
     *     operationId="login",
     *     summary="登录",
     *     tags={"后台"},
     *     description="后台登录",
     *     produces={"application/json"},
     *     @SWG\Parameter(
     *         name="email",
     *         in="formData",
     *         description="邮箱账号",
     *         required=true,
     *         type="string",
     *     ),
     *     @SWG\Parameter(
     *         name="password",
     *         in="formData",
     *         description="密码",
     *         required=true,
     *         type="string",
     *     ),
     *     @SWG\Parameter(
     *         name="source",
     *         in="formData",
     *         description="来源",
     *         required=true,
     *         type="string",
     *     ),
     *     @SWG\Response(
     *         response=200,
     *         description="操作成功",
     *         @SWG\Schema(
     *              type="object",
     *              @SWG\Property(property="code", type="integer",description="状态码"),
     *              @SWG\Property(property="msg", type="string",description="提示信息"),
     *              @SWG\Property(property="data", type="object",
     *                  @SWG\Property(property="uid", type="integer", description="用户uid"),
     *                  @SWG\Property(property="name", type="string", description="用户名"),
     *                  @SWG\Property(property="email", type="string", description="邮箱账号"),
     *                  @SWG\Property(property="created_at", type="string", description="创建时间"),
     *                  @SWG\Property(property="source", type="integer", description="来源"),
     *                  @SWG\Property(property="rules", type="array",description="规则列表",
     *                      @SWG\Items(type="object",
     *                          @SWG\Property(property="title", type="string",description="名称"),
     *                          @SWG\Property(property="path", type="string",description="路径"),
     *                          @SWG\Property(property="id", type="integer",description="id"),
     *                          @SWG\Property(property="source", type="integer",description="来源"),
     *                          @SWG\Property(property="name", type="string",description="模块"),
     *                          @SWG\Property(property="pid", type="integer",description="父id"),
     *                          @SWG\Property(property="tab_title", type="string",description="选项卡名称"),
     *                      ),
     *                  )
     *              ),
     *          )
     *     )
     * )
     */
    public function login(Request $request)
    {
        return $this->resultData('$_0');
    }

Get接口案例:

/**
     * @SWG\Get(
     *     path="/api/funds/flow_daily",
     *     operationId="daily",
     *     summary="资金流水日报",
     *     tags={"资金管理"},
     *     description="客户资金流水日报",
     *     produces={"application/json"},
     *     @SWG\Parameter(
     *         name="currency_no",
     *         in="query",
     *         description="币种号",
     *         required=false,
     *         type="string",
     *     ),
     *     @SWG\Parameter(
     *         name="page",
     *         in="query",
     *         description="页码",
     *         required=false,
     *         type="integer",
     *     ),
     *     @SWG\Parameter(
     *         name="page_size",
     *         in="query",
     *         description="每页条数：默认10条",
     *         required=false,
     *         type="integer",
     *     ),
     *     @SWG\Response(
     *          response=200,
     *          description="操作成功",
     *     )
     * )
     */
    public function daily(Request $request)
    {
        return $this->resultData('$_0');
    }

继续访问swagger页面：

http://你的域名/swagger

即可看到接口内容了

参考资料：

name - string
参数名. 通过路径传参(in 取值 "path")时有注意事项,没用到,懒得看了...
 
in - string
参数从何处来. 必填. 取值仅限: "query", "header", "path", "formData", "body"
 
description - string
参数描述. 最好别太长
 
type - string
参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"
 
required - boolean
参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.

参考文章:

https://blog.csdn.net/qq175023117/article/details/81866873