ThinkPHP5使用Swagger-php接口文档

OwenZhang

发布于 2021-12-08 14:19:13

8290

发布于 2021-12-08 14:19:13

文章被收录于专栏：Owen's World

git

环境：Centos7.1

参考了网上的一些教程，过程有点曲折。参考教程地址：www.cnblogs.com/lyh940/p/70…

开始操作：

1、用composer安装Swagger。

机器上装的有宝塔面板，为了省事儿，直接用面板的shell执行安装Swagger的命令，

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
复制代码

我这边执行之后，结果出现以下提示：

All settings correct for using Composer
The HOME or COMPOSER_HOME environment variable must be set for composer to run correctly
复制代码

正常情况下，应当提示：

All settings correct for using Composer
download……
复制代码

看到跟环境变量有关，就检查了环境变量，发现查看环境变量的结果不正确。然后想到，也许不能使用宝塔面板的shell。于是登录服务器，发现提示结果正常了。

composer安装之后，发现全局命令无法使用。

composer update

composer require zircote/swagger-php

composer global require zircote/swagger-php

每次执行composer命令，都会提示命令参数。意思是我输入的命令不对。

但是我明明进行了全局安装。也就是执行了前面的mv命令。进入到usr/local/bin/目录，发现文件也是在的。这就奇怪了。

使用composer -v命令，查看软件的版本。发现是v0.2.x，版本好像不太对，查看了一下composer网站上的版本，发现当前官网上写的是Latest: v1.8.0

难道有个软件使用的命令跟composer重名？

上面提示执行这个命令，提示命令参数，于是我就用它提示的参数composer --help，查看帮助。发现给出的帮助里面，有个网址，访问那个网址，发现是区块链账本项目介绍。原来是同事在这个服务器测试区块链项目，装的东西，冲突了。

想到能否给命令设置别名，于是将/usr/local/bin/composer改名为composer1。执行

composer1 install
复制代码

提示权限被拒绝。难道是没有权限？但是我明明使用的root账号。还是去查看了composer1文件的权限，发现root有读写权限，但没有执行权限，于是添加上执行权限，执行

composer1 install
复制代码

执行成功。

2、下载swagger-ui

用cd命令进入到存放静态文件的目录，例如public目录。执行下面命令：

git clone https://github.com/swagger-api/swagger-ui.git
复制代码

注意：上面的命令，下载的是当前最新版本3.0，但是3.0有个已知的问题，不支持中文。如果想支持中文，需要指定版本。

git clone --branch v2.2.10 https://github.com/swagger-api/swagger-ui.git
复制代码

3、安装swagger-php后端

进入tp框架找到根目录下,打开composer.json找到require项，添加一行，然后使用更新命令。

"zircote/swagger-php": "*"
复制代码

注意，每行用逗号分隔，不要忘了。

或者执行命令：

composer require "zircote/swagger-php"
复制代码

注意：这个命令默认下载的是当前最新的版本，也就是3.x。我到git上查了一下，想要跟swagger-ui的2.x版本配合使用，需要使用swagger-php 2.x版本。指定版本：

composer require "zircote/swagger-php:2.0.13"
复制代码

4、生成swagger.json文件

教程上，让执行下面命令（实际执行的命令，要根据你那边的目录来确定）

php E:/WampServer/WWW/tpSwagger/tp5/vendor/zircote/swagger-php/bin/swagger E:/WampServer/WWW/tpSwagger/tp5/vendor/zircote/swagger-php/Examples -o E:/WampServer/WWW/tpSwagger/tp5/swaggerApi/swagger.json
复制代码

第1个路径是你安装成功后组件的路径；

第2个路径是你想要生成这个目录下所有用swagger方式注释的php文件，把所有注释生成api文档；

第3个路径是你存放生成swagger.json的路径。

可能是我这边默认安装的是新版的swagger（查看版本是3.0），提示找不到swagger

我到bin这个目录，发现没有swagger文件，但是有一个openapi文件。

于是就把bin/swagger改为bin/openapi，再次执行。

结果虽然报了很多警告，但是确实生成了json文件。

5、swagger-ui加载生成的json文件

进入到swagger-ui的下载目录，找到dist目录，打开里面的index.html文件，修改文件引用的.json文件的路径为你的json文件的路径（就是上面生成的那个swagger.json）

如果json文件的目录设置不对，则会提示Failed to load API definition.

6、快速更新文档

<?php
namespace app\index\controller;

use think\Controller;
class Index extends Controller
{
    public function index(){
        $path = 'D:/WampServer/WWW/tpSwagger/tp5/application'; //你想要哪个文件夹下面的注释生成对应的API文档
        $swagger = \OpenApi\scan($path);
        // header('Content-Type: application/json');
        // echo $swagger;
        $swagger_json_path = 'D:/WampServer/WWW/tpSwagger/tp5/swaggerApi/swagger.json';
        $res = file_put_contents($swagger_json_path, $swagger);
        if ($res == true) {
           $this->redirect('http://localhost/tpSwagger/swagger-ui/dist/index.html');
        }
    }

}
复制代码

我这边在使用Swagger方法的时候，不能用这个\OpenApi\scan(path);提示找不到方法，需要用Swaggerscan(path);提示找不到方法，需要用\\Swagger\\scan(path);提示找不到方法，需要用Swaggerscan(path);

扫描的结果是对象，如果要写入文件，需要转换为字符串。另外在写入文件的时候，遇到权限问题。我最后没有使用file_put_contents函数

$path = APP_PATH.'portal/test'; //你想要哪个文件夹下面的注释生成对应的API文档
        $swagger = \Swagger\scan($path);
        // header('Content-Type: application/json');
        // echo $swagger;
        $swagger_json_path = ROOT_PATH.'public/swaggerApi/swagger.json';
        // 检测模板目录
        $dir = dirname($swagger_json_path);
        if (!is_dir($dir)) {
            mkdir($dir, 0755, true);
        }

        $myfile = fopen($swagger_json_path, "w") or die("Unable to open file!");
        $swagger=json_encode($swagger, true);
        fwrite($myfile, $swagger);
        fclose($myfile);
复制代码

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2021年10月25日，如有侵权请联系 cloudcommunity@tencent.com 删除

composer