Laravel使用swagger PHP生成api接口文档
Laravel使用swagger PHP生成api接口文档
Swagger集接口文档和测试于一体，就类比将postman和showdoc的结合体
首先要先安装基于laravel5的swagger包
地址：https://github.com/DarkaOnLine/L5-Swagger
一、安装
| Laravel | Swagger UI | OpenAPI Spec compatibility | L5-Swagger |
|---|---|---|---|
| 5.1.x | 2.2 | 1.1, 1.2, 2.0 | php composer require "darkaonline/l5-swagger:~3.0" |
| 5.2.x | 2.2 | 1.1, 1.2, 2.0 | php composer require "darkaonline/l5-swagger:~3.0" |
| 5.3.x | 2.2 | 1.1, 1.2, 2.0 | php composer require "darkaonline/l5-swagger:~3.0" |
| 5.4.x | 2.2 | 1.1, 1.2, 2.0 | php composer require "darkaonline/l5-swagger:~4.0" |
| 5.4.x | 3 | 2.0 | php composer require "darkaonline/l5-swagger:5.4.*" |
| 5.5.x | 3 | 2.0, 3.0 | php composer require "darkaonline/l5-swagger:5.5.*" |
| 5.6.x | 3 | 2.0, 3.0 | php 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控制器
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
http://*****.com/swagger#/article/article.list 要想显示article.list 则需要添加deepLinking: true
建立BaseController
这样基本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.暂时项目用到的大概就这些把，希望可以对大家有帮助。