ThinkPHP 使用 SwaggerUi 自动生成 api 文档
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 了。
