Swagger整合到ThinkPHP实践

最新推荐文章于 2023-06-08 23:00:00 发布

海阳之新

最新推荐文章于 2023-06-08 23:00:00 发布

阅读量2.3k

点赞数

分类专栏： ThinkPHP 文章标签： thinkphp swagger

本文链接：https://blog.csdn.net/vsiryxm/article/details/53465230

版权

ThinkPHP 专栏收录该内容

7 篇文章 0 订阅

订阅专栏

前言

程序员最怕写接口文档，以前的项目中都是手工写，然后公布在一个内部网址上，程序参数一修改，接口文档再手工更新一次，很费神，有了Swagger，一切变得简单化，只要把注释写好，Swagger将直接抓取注释内容自动生成接口文档，也让开发流程变得标准化。

环境

Swagger-UI、Swagger-PHP、ThinkPHP3.2.3、CentOS 6.5
Swagger的使用需要安装两个模块分别是Swagger-UI、Swagger-PHP，
在项目根目录下建立Tools文件夹，将有关接口文档的程序全部布署在此文件夹下。

1、安装swagger-ui前端

cd Tools #进入工具目录
git clone https://github.com/swagger-api/swagger-ui.git #下载swagger-ui版本

2、修改swagger-ui配置

找到swagger-ui/dist目录，打开index.html，修改swagger.json文件的路径把其中的那一串url改成自己的比如http://petstore.swagger.io/v2/swagger.json
注释掉：

//var url = window.location.search.match(/url=([^&]+)/);
//if (url && url.length > 1) {
     //  url = decodeURIComponent(url[1]);
//} else {
     //  url = "http://petstore.swagger.io/v2/swagger.json";
//}

在上面代码之后新增：（Tools下新建swagger-docs/v1.8，v1.8即迭代版本号，以后迭代一次新建一个版本文件夹）

var url = document.location.protocol+'//'+document.domain+'/Tools/swagger-docs/v1.8/swagger.json'; #下面的程序将把最新的swagger.json文件生成到这里

如果你想支持中文在index.html中加上

<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script><!--将en.js改成zh-cn.js-->

3、安装swagger-php后端

cd Tools  #进入工具目录
composer require zircote/swagger-php  #通过composer来安装

4、手工生成swagger.json

php  /project_root/Tools/vendor/zircote/swagger-php/bin/swagger /project_root/Tools/vendor/zircote/swagger-php/Examples -o  /project_root/Tools/swagger-docs/v1.8/swagger.json

执行完后，在v1.8目录下即可看到json文件。

5、动态生成swagger.json

为了让前端开发人员每次打开接口文档，看到的都是最新的接口内容，我们必须让这个swagger.json能自动生成。
假设我们的目录结构是这样的：project_root/Application/Api，也就是说这里是我们每次请求接口的模块，在Api\Controller\IndexController.class.php文件中写一个doc()方法，用来动态生成swagger.json，然后跳转到swagger-ui的呈现首页（dist/index.html），代码如下：

class IndexController extends Controller
{
    public function __construct()
    {
        parent::__construct();
    }

    /* 接口文档入口 */
    public function doc()
    {
        $pet = I('get.pet', 0, 'int');
        $path = 1==$pet ? 'Tools/vendor/zircote/swagger-php/Examples' : 'Application/Api'; //如果需要看pet示例，带参数pet=1即可
        $swagger = \Swagger\scan($path);
        //header('Content-Type: application/json');
        //echo $swagger;
        $swagger_path = 'Tools/swagger-docs/v1.8/swagger.json';
        $res = file_put_contents($swagger_path, $swagger);
        if (true == $res) {
            $this->redirect('/Tools/swagger-ui/dist/index.html');
        } else {
            echo 'swagger.json写入失败！';
        }
    }

}