[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 IlluminateHttpRequest;

use SwaggerAnnotations as SWG;

 

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

*      // define tag

*     @SWGTag(name="Home", description="Roote Route"),
*     @SWGTag(name="User", description="UserController"),
*     @SWGTag(name="Role", description="RoleController"),
*     @SWGExternalDocumentation(
*         description="Find out more about my website",
*         url="http..."
*     ),
*    @SWGDefinition(
*       definition="errorModel",
*       required={"status code", "message"},
*       @SWGProperty(
*           property="status code",
*           type="integer",
*           format="int32"
*       ),
*       @SWGProperty(
*           property="message",
*           type="string"
*       )
*   ),

*    // 定义 API
*   @SWGDefinition(
*     definition="Login",
*      @SWGProperty(
*        property="useraccount",
*        type="string"
*      ),
*      @SWGProperty(
*         property="password",
*         type="string"
*      )
*    ),
*    @SWGDefinition(
*       definition="logout",
*       @SWGProperty(
*           property="token",
*           type="string"
*       )
*   ),
* )
 */

 

class SwaggerController extends Controller

{

public function doc()

{

$swagger = Swaggerscan(realpath(__DIR__.’/../../’));

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

}

}

 

 

具体 UserController.php 中 Swagger Definition

 

/**
 * @SWGPost(
 *     path="/user/login",
 *     summary="Sign in",
 *     tags={"User"},
 *     operationId="Login",
 *     description="Login",
 *     produces={"application/json"},
 *     @SWGParameter(
 *         name="account & password",
 *         in="body",
 *         description="Login",
 *         required=true,
 *         @SWGSchema(ref="#/definitions/Login"),
 *     ),
 *     @SWGResponse(
 *         response=200,
 *         description="It's ok"
 *     ),
 *     @SWGResponse(
 *         response="default",
 *         description="unexpected error",
 *         @SWGSchema(ref="#/definitions/errorModel")
 *     )
 * )
 * @param Request $request
 * @return IlluminateHttpJsonResponse
 */
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 @SWGInfo() not found

 

方法： use SwaggerAnnotations as SWG;

 

The problem is - you're missing the @SWGInfo 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