如何在 Laravel 项目中使用 Swagger
安装依赖 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 出现报错总结：
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:
还必须在类定义的前面，添加上下面的这段：
Can't read swagger JSON
检查 JSON 接口 URL 时候正确
