如何在 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