TP5.1（TP系列都可以使用）继承swagger文档注释

写在前面：可能会遇到php的版本不支持，我这里使用的是php7.1。

swagger是什么

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

安装

首先进入您的项目，然后运行下面的命令会自动在项目中获取到3.0的swagger

composer require zircote/swagger-php:*

会自动在项目的verdor中生成下面这个文件

到这里就已经安装成功了。

现在来配置生成swagger.json的function，这个json文件就是我们的注释文件生成的，我们通过访问某个页面就可以看到具体的效果了

现在开始~

在你的class前面加入这样的一个代码

/**
 * @OA\Info(
 *     title="Auth API",
 *     version="1.0"
 * )
 */
 #这个是申明文档的标题及版本，注意：代码中只用加一个这个就可以了

在你的function中加入这样的一个代码

public function create_swagger()
    {
        $path              = APP_PATH; //申明生成文档的路径
        $swagger           = \OpenApi\scan($path); //初始化swagger生成函数
        $swagger_json_path = 'swagger.json'; //swagger的存放路径，可以填相对地址
        $res = file_put_contents($swagger_json_path, $swagger->toJson()); //调用写入json的方法
        //var_dump($res);
    }

至此你的swagger生成的方法就已经完成了。现在需要写注释文档用于去生成swagger文件

在你要生成文档的前面加入这样的一个注释，具体的可以看官方文档

/**
     * @OA\Get(
     *     path="/api/api/getBanner", //当前方法的相对路径（简单来说就是通过url可以访问的路径）
     *     tags={"index"},
     *     summary="获取轮播图",
     *     description="获取轮播图",
     *     operationId="waiting",
     *     @OA\Response(
     *         response="default",
     *         description="201"
     *     ),
     *     @OA\RequestBody(
     *         description="请求的东西",
     *     )
     * )
     */

现在你已经生成了一个注释的json文件，那我们怎么看到这个接口文档呢

首先下载swagger-ui，下方是下载地址，下载下来的东西很多，但是整体来说有用的只有dist这个文件夹里面的东西，如果你在下个项目想用只需要将这个文件夹拷贝过去

下载地址：https://github.com/swagger-api/swagger-ui/

将dist放在你的public文件中，可以随便改个名字，就像下面这样的

现在找到上图中的index.html，修改一下swagger.json的路径

<script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "../swagger.json", //将这个url修改为你的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
    }
  </script>

现在可以通过访问function生成你的json文件了，我一般习惯在开发环境用定时任务去生成。

生成：url/api/cron/create_swagger
查看文档：url/swagger-ui