[Laravel-Swagger]如何在 Laravel 项目中使用 Swagger

如何在 Laravel 项目中使用 Swagger

http://swagger.io/getting-started/

安装依赖 swagger-php

composer require zircote/swagger-php

创建 SwaggerController，用于为了 swagger-php 提供 json 数据

php artisan make:controller SwaggerController

给 SwaggerController 加上 SwaggerJSON 数据的处理：

SwaggerController.php 

use Illuminate\Http\Request;

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     schemes={"http","https"},
 *     host="api.host.com",
 *     basePath="/",
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="This is my website cool API",
 *         description="Api description...",
 *         termsOfService="",
 *         @SWG\Contact(
 *             email="contact@mysite.com"
 *         ),
 *         @SWG\License(
 *             name="Private License",
 *             url="URL to the license"
 *         )
 *     ),
 *     @SWG\ExternalDocumentation(
 *         description="Find out more about my website",
 *         url="http..."
 *     ),

*      // define tag

*     @SWG\Tag(name="Home", description="Roote Route"),
*     @SWG\Tag(name="User", description="UserController"),
*     @SWG\Tag(name="Role", description="RoleController"),
*     @SWG\ExternalDocumentation(
*         description="Find out more about my website",
*         url="http..."
*     ),
*    @SWG\Definition(
*       definition="errorModel",
*       required={"status code", "message"},
*       @SWG\Property(
*           property="status code",
*           type="integer",
*           format="int32"
*       ),
*       @SWG\Property(
*           property="message",
*           type="string"
*       )
*   ),

*    // 定义 API
*   @SWG\Definition(
*     definition="Login",
*      @SWG\Property(
*        property="useraccount",
*        type="string"
*      ),
*      @SWG\Property(
*         property="password",
*         type="string"
*      )
*    ),
*    @SWG\Definition(
*       definition="logout",
*       @SWG\Property(
*           property="token",
*           type="string"
*       )
*   ),
* )
 */

class SwaggerController extends Controller

{

public function doc()

{

$swagger = \Swagger\scan(realpath(__DIR__.’/../../’));

return response()->json($swagger);

}

}

具体 UserController.php 中 Swagger Definition

/**
 * @SWG\Post(
 *     path="/user/login",
 *     summary="Sign in",
 *     tags={"User"},
 *     operationId="Login",
 *     description="Login",
 *     produces={"application/json"},
 *     @SWG\Parameter(
 *         name="account & password",
 *         in="body",
 *         description="Login",
 *         required=true,
 *         @SWG\Schema(ref="#/definitions/Login"),
 *     ),
 *     @SWG\Response(
 *         response=200,
 *         description="It's ok"
 *     ),
 *     @SWG\Response(
 *         response="default",
 *         description="unexpected error",
 *         @SWG\Schema(ref="#/definitions/errorModel")
 *     )
 * )
 * @param Request $request
 * @return \Illuminate\Http\JsonResponse
 */
public function login( Request $request)
{
    $arr_user_info = [];
    $ret = $this->validateLogInfo($request, $arr_user_info);

if ($ret) {
        return $ret;
    }

$ret = $this->verifyLogInfo($arr_user_info);

if ($ret) {
        return $ret;
    }
}

在 Laravel 中使用 Swagger 出现报错总结：

1. ErrorException in Logger.php line 38: Required @SWG\Info() not found

方法： use Swagger\Annotations as SWG;

The problem is - you're missing the @SWG\Info block. It's a block which tells swagger some most common information about your API.

I usually put this in a separate controller which is rendering swagger JSON. Here's an example:

还必须在类定义的前面，添加上下面的这段：

1. Can't read swagger JSON

检查 JSON 接口 URL 时候正确

安装使用参考教程：https://segmentfault.com/a/1190000004980342