swagge php token,Laravel使用swagger PHP生成api接口文档

Laravel使用swagger PHP生成api接口文档

Swagger集接口文档和测试于一体，就类比将postman和showdoc的结合体

首先要先安装基于laravel5的swagger包

一、安装

LaravelSwagger UIOpenAPI Spec compatibilityL5-Swagger5.1.x2.21.1, 1.2, 2.0php composer require "darkaonline/l5-swagger:~3.0"

5.2.x2.21.1, 1.2, 2.0php composer require "darkaonline/l5-swagger:~3.0"

5.3.x2.21.1, 1.2, 2.0php composer require "darkaonline/l5-swagger:~3.0"

5.4.x2.21.1, 1.2, 2.0php composer require "darkaonline/l5-swagger:~4.0"

5.4.x32.0php composer require "darkaonline/l5-swagger:5.4.*"

5.5.x32.0, 3.0php composer require "darkaonline/l5-swagger:5.5.*"

5.6.x32.0, 3.0php composer require "darkaonline/l5-swagger:5.6.*"

二、

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

复制代码

三、Open your AppServiceProvider (located in app/Providers) and add this line in register function

$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);

复制代码

or open your config/app.php and add this line in providers section

L5Swagger\L5SwaggerServiceProvider::class,

复制代码

我仍在使用Swagger @SWG注释

如果在项目中仍然使用Swagger @SWG注释，您应该：

swagger-php通过运行以下命令在您的项目作曲家中明确要求版本2. *：

composer require 'zircote/swagger-php:2.*'

复制代码

在你的config/l5-swagger.php：

'swagger_version' => env('SWAGGER_VERSION', '2.0'),

复制代码

建立swaggerController控制器

namespace App\Http\Controllers;

use Illuminate\Http\Request;

use Swagger\Annotations as SWG;

class SwaggerController extends Controller

{

/**

* @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="",

* ),

* )

*/

public function getJSON()

{

// 正式环境(production)访问swagger文档时返回空

if (config('app.env') == 'production') {

return response()->json([], 200);

}

$swagger = \Swagger\scan(app_path('/'));

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

}

}

复制代码

在routes/web.php下加入如下代码

Route::get('/swagger', function () {

return view('vendor.l5-swagger.index',['urlToDocs' => '/doc/json']);

});

Route::group(['prefix' => 'doc'], function () {

Route::get('json', 'SwaggerController@getJSON');

});

复制代码

通过你的域名/swager可以访问到接口、域名/doc/json访问到的是json

​

建立BaseController

namespace App\Http\Controllers\V1;

use App\Http\Controllers\Controller ;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

use Illuminate\Foundation\Auth\AuthenticatesUsers;

use Illuminate\Foundation\Bus\DispatchesJobs;

use Illuminate\Foundation\Validation\ValidatesRequests;

use Illuminate\Http\Request;

use Illuminate\Support\Facades\Route;

class BaseController extends Controller

{

use AuthenticatesUsers ;

/**

* @SWG\Swagger(

* host="",

* basePath="/api/v1",

* @SWG\Info(

* title="app",

* version="1.0.0"

* ),

* @SWG\SecurityScheme(

* securityDefinition="api_key",

* type="apiKey",

* in="header",

* description = "认证token Bearer+空格+token",

* name="Authorization"

* ),

* )

*/

public function __construct()

{

}

}

复制代码

这样基本swagger文档就搭建成功了

每个接口编写 swagger 格式的注释会有很多种、下面举几个例子

Get请求

/**

* @SWG\Get(

* path="/article/list",

* tags={"article"},

* operationId="article.list",

* summary="获取知识库列表(分页)",

* consumes={"application/json"},

* produces={"application/json"},

* security={{"api_key": {"scope"}}},

* @SWG\Parameter(in="query",name="page",description="页码",required=false,type="integer",),

* @SWG\Parameter(in="query",name="title",description="知识库标题",required=false,type="string",),

* @SWG\Parameter(in="query",name="type_id",description="类型id",required=false,type="integer",),

* @SWG\Parameter(in="query",name="pid",description="产品编号",required=false,type="string",),

* @SWG\Response(

* response=200,

* description="",

* @SWG\Schema(

* type="object",

* @SWG\Property(property="code", type="string",description="状态码"),

* @SWG\Property(property="message", type="string",description="提示信息"),

* @SWG\Property(property="data", type="object",

* @SWG\Property(property="current_page", type="string", description="现在的页码"),

* @SWG\Property(property="first_page_url", type="string", description="第一页URL"),

* @SWG\Property(property="from", type="integer", description="开始"),

* @SWG\Property(property="last_page", type="string", description="最后一页页码"),

* @SWG\Property(property="last_page_url", type="string", description="最后一页url"),

* @SWG\Property(property="next_page_url", type="integer", description="下一页url"),

* @SWG\Property(property="path", type="string",description="路径"),

* @SWG\Property(property="per_page", type="integer", description="每页显示数量"),

* @SWG\Property(property="prev_page_url", type="string",description="上一页地址"),

* @SWG\Property(property="to", type="integer", description="结束"),

* @SWG\Property(property="total", type="integer", description="总条数"),

* @SWG\Property(property="lists", type="array",

* @SWG\Items(type="object",

* @SWG\Property(property="aid", type="string",description="知识库编号"),

* @SWG\Property(property="title", type="string",description="标题"),

* @SWG\Property(property="content", type="string",description="内容"),

* @SWG\Property(property="created_at", type="string",description="创建时间"),

* @SWG\Property(property="views", type="integer",description="浏览数量"),

* @SWG\Property(property="product_name", type="string",description="产品名称"),

* @SWG\Property(property="type_name", type="string",description="类型名称"),

* ),

* ),

* ),

* )

* ),

* )

*/

复制代码

get请求效果如下：

​

​

Post请求

/**

* @SWG\Post(

* path="/article/create",

* tags={"article"},

* operationId="create_article",

* summary="创建知识库",

* consumes={"application/json"},

* produces={"application/json"},

* security={{"api_key": {"scope"}}},

* @SWG\Parameter(

* in="body",

* name="data",

* description="",

* required=true,

* @SWG\Schema(

* type="object",

* @SWG\Property(property="pid",description="产品编号",type="string"),

* @SWG\Property(property="uids",type="array",

* @SWG\Items(type="integer",description="成员编号"),

* ),

* )

* ),

* @SWG\Response(

* response=200,

* description="",

* @SWG\Schema(

* type="object",

* @SWG\Property(property="code", type="string",description="状态码"),

* @SWG\Property(property="message", type="string",description="提示信息"),

* )

* ),

* )

*/

复制代码

post请求效果如下：

​

接口描述 (@SWG\Get, @SWG\Post 等) 常用字段:

summary - string

接口的简要介绍,会显示在接口标头上,不能超过120个字符

description - string

接口的详细介绍

externalDocs - string

外部文档链接

operationId - string

全局唯一的接口标识

consumes - [string]

接口接收的MIME类型

produces - [string]

接口返回的MIME类型,如 application/json

schemes -[string]

接口所支持的协议,取值仅限: "http", "https", "ws", "wss"

parameters -[Parameter Object | Reference Object]

参数列表

复制代码

参数描述 (@SWG\Parameter) 常用字段:

name - string

参数名. 通过路径传参(in 取值 "path")时有注意事项,没用到,懒得看了...

in - string

参数从何处来. 必填. 取值仅限: "query", "header", "path", "formData", "body"

description - string

参数描述. 最好别太长

type - string

参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"

required - boolean

参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.

复制代码

暂时项目用到的大概就这些把，希望可以对大家有帮助。