如何在 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 出现报错总结：
- 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 时候正确
安装使用参考教程：https://segmentfault.com/a/1190000004980342