1、下载swagger-ui
GitHub地址：https://github.com/swagger-api/swagger-ui
2、修改 ThinkPHP 的 build.php ，执行命令生成需要创建的模块
// 定义api模块的自动生成 （按照实际定义的文件名生成）
'api' => [
'__file__' => ['common.php'],
'__dir__' => ['controller'],
'controller' => ['Passport'],
'model' => [],
'view' => [],
],
命令： php think build
3、修改刚刚生成的模块下的 config.php 文件
return [
'default_return_type' => 'json', // 修改控制器默认输出json对象
'url_param_type' => 1, // URL参数方式 0 按名称成对解析 1 按顺序解析
];
4、在刚刚生成的 application/api/contorller/Passport.php 下添加这几个方法
<?php
namespace app\api\controller; /**
* swagger: 登录相关
*/
class Passport
{
/**
* post: 发送验证码
* path: sendVerify/{phone}/{deviceType}
* method: sendVerify
* param: phone - {string} 手机号
* param: deviceType - {int} = [0|1|2|3|4] 设备类型(0: android手机, 1: ios手机, 2: android平板, 3: ios平板, 4: pc)
*/
public function sendVerify($phone, $deviceType) {
return [
'code' => 200,
'message' => '发送验证码',
'data' => [
'phone' => $phone,
'deviceType' => $deviceType
]
];
} /**
* post: 登陆
* path: login
* method: login
* param: phone - {string} 手机号
* param: password - {string} 密码
* param: deviceType - {int} = [0|1|2|3|4] 设备类型(0: android手机, 1: ios手机, 2: android平板, 3: ios平板, 4: pc)
* param: verifyCode - {string} = 0 验证码
*/
public function login($phone, $password, $deviceType, $verifyCode = '0') {
return [
'code' => 200,
'message' => '登陆成功',
'data' => [
'phone' => $phone,
'password' => $password,
'deviceType' => $deviceType,
'verifyCode' => $verifyCode
]
];
} /**
* get: 获取配置
* path: profile
* method: profile
* param: keys - {string[]} 需要获取配置的Key值数组
*/
public function profile($keys) {
return [
'code' => 200,
'message' => '获取成功',
'data' => $keys
];
}
}
5、把 swagger-ui 目录下的 dist 放到你的 public 目录下，然后更名为 swagger。
6、修改 swagger 下 index.html 的路径：
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url : window.location.href.replace(window.location.hash, "").replace(/[^/]+$/, "swagger.json"),
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}
7、整合ThinkPHP 和 swaggerUI：
在 public 目录下新建 api.php
<?php // +----------------------------------------------------------------------
// | ThinkPHP SWAGGER [ 够用就好 ]
// +----------------------------------------------------------------------
// | Copyright (c) 2016 http://jitlee.com All rights reserved.
// +----------------------------------------------------------------------
// | Licensed ( http://jitlee.com/licenses/LICENSE-1.0 )
// +----------------------------------------------------------------------
// | Author: Jitlee.Wan <www.wpj@163.com>
// +---------------------------------------------------------------------- // 定义应用目录
define('APP_PATH', __DIR__ . '/../application'); $tags = array(); // Tags对象
$paths = array(); // Path数组 $module_dir = opendir(APP_PATH);
while (($module_name = readdir($module_dir)) !== false) {
if ($module_name != 'api') continue; //可以自己设置需要哪些模块用作api输出页面
$module_path = APP_PATH . DIRECTORY_SEPARATOR . $module_name; //构建子目录路径
if (is_dir($module_path)) {
$module = strtolower($module_name); $module_child_dir = opendir($module_path);
while (($module_child_name = readdir($module_child_dir)) !== false) {
$module_child_path = $module_path . DIRECTORY_SEPARATOR . $module_child_name; //构建子目录路径
if (is_dir($module_child_path) && $module_child_name == 'controller') {
$controller_dir = opendir($module_child_path);
while (($controller_file = readdir($controller_dir)) !== false) {
$controller_path = $module_child_path . DIRECTORY_SEPARATOR . $controller_file; //构建子目录路径
$controller_name = strtolower(basename($controller_path, '.php'));
$contents = file_get_contents($controller_path);
if (preg_match_all('/swagger:\s*([^\n]+)/i', $contents, $swagger_matches)) { // 添加tag
$found_tag = false;
foreach ($tags as $tag) {
if ($tag['name'] == $controller_name) {
$found_tag = true;
break;
}
}
if (!$found_tag) {
array_push($tags, array(
'name' => $controller_name,
'description' => $swagger_matches[1][0]
));
} // 添加path
if (preg_match_all('/\/\*((?!\*\/).)+\*\//s', $contents, $func_matches)) {
$length = count($func_matches[0]);
if ($length > 1) {
for ($i = 1; $i < $length; $i++) {
$func_array = array(); // 解析每个方法
$func_contents = $func_matches[0][$i]; // 方法说明
if (!preg_match_all('/(get|post|delete)\s*:\s*([^\n]+)/i', $func_contents, $matches)) {
break;
}
$method = $matches[1][0];
$summary = $matches[2][0]; // 路径
if (!preg_match_all('/path\s*:\s*([^\n]+)/i', $func_contents, $matches)) {
break;
}
$path = $matches[1][0]; // 方法名称
$operations = explode('/', $path);
$operationId = $operations[0];
if (preg_match_all('/method\s*:\s*([^\n]+)/i', $func_contents, $matches)) {
$operationId = $matches[1][0];
} $paths[$path] = array();
$parameters = array();
$func = array(
'tags' => [$controller_name],
'summary' => $summary,
'description' => '',
'operationId' => $operationId,
'produces' => ['application/json']
); // 参数
$pattern = '/param\s*:\s*(?<name>\w+)\s*-\s*\{(?<type>\w+(?<array>\[\])?)\}\s*(=\s*((\[(?<enum>[^]]+)\])|(?<default>[^\s]+))\s*)?(?<summary>[^*]+)/i';
if (preg_match_all($pattern, $func_contents, $matches)) {
$names = $matches['name']; // 参数名称
$types = $matches['type']; // 参数类型
$enums = $matches['enum']; // 参数枚举
$defaults = $matches['default']; // 默认值
$summarys = $matches['summary']; // 参数说明
$arrays = $matches['array']; // 参数说明 $params_count = count($names);
for ($j = 0; $j < $params_count; $j++) {
$in = $method == 'get' ? 'query' : 'formData';
if (strpos($path, '{' . $names[$j] . '}') !== false) {
$in = 'path';
} $parameter = array(
'name' => $names[$j],
'in' => $in,
'required' => true,
'description' => $summarys[$j]
); if ($defaults[$j] !== '') {
$parameter['required'] = false;
$parameter['defaultValue'] = $defaults[$j];
} $type = str_replace('[]', '', $types[$j]);
if ($type == 'int') {
$type = 'integer';
} if ($arrays[$j] != '') { // 是否数据参数
$parameter['type'] = 'array';
$parameter['items'] = array(
'type' => str_replace('[]', '', $type)
);
$parameter['collectionFormat'] = 'brackets'; // url带中括号
// $parameter['collectionFormat'] = 'multi'; // url不带中括号
} else if ($enums[$j] != '') { // 是否枚举参数
$enum = explode('|', $enums[$j]);
$parameter['type'] = $type;
$parameter['enum'] = $enum;
} else {
$parameter['type'] = $type;
}
array_push($parameters, $parameter);
}
}
$func['parameters'] = $parameters;
// 生成api访问路径
$paths['/' . $module . '/' . $controller_name . '/' . $path][$method] = $func;
}
}
}
}
}
closedir($controller_dir);
}
}
closedir($module_child_dir);
}
}
closedir($module_dir); $swagger = array(
'swagger' => '2.0',
'info' => array(
'description' => 'APP 后台服务',
'version' => '1.0.0',
'title' => '［我的APP］Swagger',
'termsOfService' => 'http://www.ritacc.cn/',
'contact' => array(
'email' => 'www.wpj@163.com'
),
'license' => array(
'name' => 'Apache 2.0',
'url' => 'http://www.apache.org/licenses/LICENSE-2.0.html'
)
),
'host' => $_SERVER['SERVER_NAME'] . ':' . $_SERVER['SERVER_PORT'],
'basePath' => '',
'tags' => $tags,
'schemes' => [
'http'
],
'paths' => $paths,
'securityDefinitions' => array(),
'definitions' => array(),
'externalDocs' => array(
'description' => 'Find out more about Swagger',
'url' => 'http://swagger.io'
)
); $jsonFile = fopen("swagger/swagger.json", "w") or die("Unable to open file!");
fwrite($jsonFile, json_encode($swagger));
fclose($jsonFile); // 跳转到Swagger UI
$url = '/swagger/index.html';
Header('HTTP/1.1 303 See Other');
Header("Location: $url");
exit;
8、打开浏览器运行 public 下的 api.php 就 ok 了。
