Laravel5.5.x集成Swagger (L5-Swagger) 只讲Laravel5.5.x的集成,laravel其他版本请自行研究或参考github上的说明
--------上图 截取自Github 官网上的安装参考-----------------------------------------------------------------------------------------------------------------------------------------------------------
本人只用到了Laravel5.5.x， 所以只讲此版本的安装，所有步骤如下
①步骤1：
在你搭建的laravel项目根目录中执行命令： composer require "darkaonline/l5-swagger:5.5.*"
②步骤2：
继续在项目根目录中执行命令： php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
执行该命令后，会在config目录下产生一个l5-swagger.php的配置文件，里面包含了swagger标题，token验证，路由等常用的基本配置
其中’generate_always’配置可以根据需要修改下，它表示是否每次都刷新swagger, 示例如下：
'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false), // 把false改为true,你每次修改了配置它就会马上更新, 否则你更改了配置它不会马上生效
③步骤3：
在项目根目录中执行命令： composer require 'zircote/swagger-php:2.*'
然后启动项目，浏览器访问测试：你的网站地址/api/documentation 可以看到swagger的界面了，但会提示缺少api-docs.json文件。
需在项目app下创建个php文件(注意：我是直接放在app文件夹下,放在app/http的Controllers文件夹下也可以)，命名为：swagger.php 文件内容如下：
<?php
/**
* Class Controller
*
* @package App\Http\Controllers
*
* @SWG\Swagger(
* basePath="",
* host="127.0.0.1",
* schemes={"http"},
* @SWG\Info(
* version="1.0",
* title="OpenApi",
* @SWG\Contact(name="Pek Ratanak", url="https://www.google.com"),
* ),
* @SWG\Definition(
* definition="Error",
* required={"code", "message"},
* @SWG\Property(
* property="code",
* type="integer",
* format="int32"
* ),
* @SWG\Property(
* property="message",
* type="string"
* )
* )
* )
*/
④步骤4：在项目根目录中执行命令： php artisan l5-swagger:generate // 如果上面不创建swagger.php 如果执行此命令就会抛出错误： In Logger.php line 38: Required @SWG\Info() not found 切忌！
现在重新访问 你的网站地址/api/documentation 刷新swagger就可以了 如图：
在app/http/Controllers文件夹下ApiController.php代码如下：
<?php
/**
* Created by PhpStorm.
* User: compter
* Date: 2018/8/30
* Time: 15:17
*/
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class ApiController extends Controller
{
/**
* @SWG\GET(
* path="/api/index",
* summary="api index by tags",
* tags={"测试"},
* description="返回测试内容",
* operationId="apIndex",
* produces={"application/json"},
* @SWG\Parameter(
* name="tags",
* in="query",
* description="拿数据的理由",
* required=true,
* type="string",
* ),
* @SWG\Response(
* response=200,
* description="Dashboard overview."
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized action.",
* )
* )
*/
public function index(Request $request)
{
return response()->json([
'result' => [
'statistics' => [
'users' => [
'name' => 'Name',
'email' => '213213@qq.com'
]
],
],
'message' => '',
'type' => 'success',
'status' => 0
]);
}
}
添加laravel的路由中 Route::get('/api/index','ApiController@index');
重新访问刷新页面即可 ----------我的预览图如下
以下为get方法的一些案例演示
<?php
/**
* Created by PhpStorm.
* User: compter
* Date: 2018/8/30
* Time: 15:17
*/
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class ApiController extends Controller
{
//前端测试用接口
public function a () {
return [
'name' => '急急急',
'sex' => 18,
];
}
/**
* @SWG\GET(
* path="/api/index",
* summary="接口简介",
* tags={"接口标签,可以是多个"},
* description="接口描述,支持 Markdown 语法",
* operationId="操作的ID,需要唯一",
* produces={"application/json"},
* @SWG\Parameter(
* name="tags",
* in="query",
* description="拿数据的理由",
* required=true,
* type="string",
* ),
* @SWG\Response(
* response=200,
* description="Dashboard overview."
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized action.",
* )
* )
*/
public function index(Request $request)
{
return response()->json([
'result' => [
'statistics' => [
'users' => [
'name' => 'Name',
'email' => '213213@qq.com'
]
],
],
'message' => '',
'type' => 'success',
'status' => 0
]);
}
}
<?php
/**
* 我的主页面
* User: computer
* Date: 2018/8/31
* Time: 15:21
*/
namespace App\Http\Controllers\MySelf;
use App\Http\Controllers\Controller;
use App\Models\Accountee;
use App\Models\Channel;
use Illuminate\Support\Facades\Auth;
class HomeController extends Controller
{
/**
* @SWG\Get(
* path="/my_self/home/index",
* summary="我的主页面",
* tags={"我的主页面"},
* description="我的主页面",
* operationId="home.index",
* produces={"application/json"},
* @SWG\Response(
* response=200,
* description="基本信息",
* @SWG\Schema(
* type="json",
* @SWG\Property(
* property="channel_id",
* type="integer",
* description="资产渠道id"
* ),
* @SWG\Property(
* property="telephone",
* type="string",
* description="手机号"
* ),
* @SWG\Property(
* property="short_name",
* type="string",
* description="企业简称"
* )
* )
* ),
* @SWG\Response(
* response=422,
* description="error",
* )
* )
*/
public function index()
{
$channel=Channel::find(100033,['id','telephone','short_name']);
$channel['telephone']=substr_replace($channel->telephone,'*****',3,5); // 手机号脱敏
return $channel;
}
}
<?php
/**
* 用户资料管理
* User: computer
* Date: 2018/8/31
* Time: 15:21
*/
namespace App\Http\Controllers\MySelf;
use App\Http\Controllers\Controller;
use App\Models\InfoPerson;
use Illuminate\Http\Request;
class UserController extends Controller
{
/**
* @SWG\Get(
* path="/my_self/user/index",
* summary="用户资料管理",
* tags={"用户列表"},
* description="用户资料列表",
* operationId="user.index",
* produces={"application/json"},
* @SWG\Parameter(
* name="page",
* in="query",
* description="分页编号,默认1",
* type="integer",
* ),
* @SWG\Parameter(
* name="pagesize",
* in="query",
* description="每页显示条数,默认10",
* type="integer",
* ),
* @SWG\Response(
* response=200,
* description="用户列表",
* @SWG\Schema(
* type="json",
* @SWG\Property(
* property="pages",
* @SWG\Property(
* property="totalnum",
* type="integer",
* description="记录总数",
* ),
* @SWG\Property(
* property="totalpage",
* type="integer",
* description="总页数",
* ),
* @SWG\Property(
* property="pagesize",
* type="integer",
* description="每页显示记录数",
* ),
* @SWG\Property(
* property="page",
* type="integer",
* description="当前页数",
* ),
* ),
* @SWG\Property(
* property="lists",
* @SWG\Items(
* @SWG\Property(
* property="id",
* type="integer",
* description="id",
* ),
* @SWG\Property(
* property="source",
* type="string",
* description="数据来源",
* ),
* @SWG\Property(
* property="industry_no",
* type="integer",
* description="行业编号",
* ),
* @SWG\Property(
* property="channel_id",
* type="integer",
* description="渠道id",
* ),
* @SWG\Property(
* property="name",
* type="string",
* description="名称",
* ),
* )
* ),
* ),
* ),
* @SWG\Response(
* response=422,
* description="error",
* )
* )
*/
public function index(Request $request){
$channel_id=2;
$page = $request->input('page',1);
$pagesize = $request->input('pagesize',PAGE_SIZE);
$offset = ($page - 1) * $pagesize;
$condition = InfoPerson::where('channel_id',$channel_id)->orderBy('id', 'desc');
$total = $condition->count();
if (empty($total)) abort(422, '没有对应的数据');
$lists = $condition->offset($offset)->limit($pagesize)->get();
return [
'pages' => [
'totalnum' => $total,
'totalpage' => intval(ceil($total / $pagesize)),
'pagesize' => $pagesize,
'page' => $page,
],
'lists' => $lists
];
}
}
记得都要添加路由哦！至于post api有空再写...
