项目调研：Swagger在PHP项目中的使用实践

上一篇文章我们一起学习了什么是swagger以及如何用官方提供的标准规范和语言（Json或者YAML）来生成我们的接口文档。但是我们部门的项目都是PHP开发的，要接入这个swagger，应该怎么做呢？今天这篇文章就是来做这个实践！
 
上一篇说的那么官方的介绍，但是这个swagger到底是个什么鬼呢？其实，说白了理解起来也很简单：

其实就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件（或者YAML）, 再通关Swagger前端来美化,整理JSON数据.

 
所以，看到这里，我们就知道了。要使用Swagger需要安装2个东西：
 

1. 前端,用来显示;
2. 后端, 用来生成JSON

 
1, 安装前端
 
swagger-ui下载

git clone https://github.com/swagger-api/swagger-ui.git

下载之后找到dist目录, 打开index.html把其中的那一串url改成自己的, 比如 http//localhost/yii2/swagger-docs/swagger.json
 

$(function () {

      var url = window.location.search.match(/url=([^&]+)/);

      if (url && url.length > 1) {

        url = decodeURIComponent(url[1]);

      } else {

        url = "http://localhost/yii2/swagger- ... 3B%3B

      }

还可以把界面调整成中文, 放开js文件的注释即可

<script src='lang/translator.js' type='text/javascript'></script>

<!-- <script src='lang/ru.js' type='text/javascript'></script> -->

<script src='lang/zh-cn.js' type='text/javascript'></script>

然后打开URL就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用, 直接访问前端就好

http://localhost/yii2/swagger-ui/dist/index.html

2, 安装后端

git clone https://github.com/zircote/swagger-php.git

因为公司用的是yii2, 所以使用了composer来安装

"require": { "zircote/swagger-php": "*" }

之后composer update, 或者直接命令行, 详见官方安装指南。

DCdeMacBook-Pro:yii2 DC$ php composer.phar require zircote/swagger-php

把swagger-php放在根目录下，然后用官方提供的Examples来生成测试json

cd swagger-php

mkdir doc 

php swagger.phar Examples -o doc

"-o" 前面代表API源目录, 即你想要生成哪个目录的API文档, 你的项目代码目录. "-o" 后面是生成到哪个path。我没有进入到swagger-php下面, 直接打的命令行, 任意路径下都可以执行生成json操作

php /Users/DC/www/yii2/vendor/zircote/swagger-php/bin/swagger /Users/DC/www/yii2/vendor/zircote/swagger-php/Examples -o /Users/DC/www/yii2/swagger-docs

然后再看http//localhost/yii2/swagger-ui/dist/index.html, 生成了API文档。
 
准备工作都做好了, 那就写代码注释就行了, 注释怎么写? 官方参考文档
 
比如Model：

/**

* @SWG\Model(

* id="vps",

* required="['type', 'hostname']",

*  @SWG\Property(name="hostname", type="string"),

*  @SWG\Property(name="label", type="string"),

*  @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")

* )

*/

class HostVps extends Host implements ResourceInterface

{

    // ...

}

比如Controller：

/**

 * @SWG\Resource(

 *  basePath="http://skyapi.dev",

 *  resourcePath="/vps",

 *  @SWG\Api(

 *   path="/vps",

 *   @SWG\Operation(

 *    method="GET",

 *    type="array",

 *    summary="Fetch vps lists",

 *    nickname="vps/index",

 *    @SWG\Parameter(

 *     name="expand",

 *     description="Models to expand",

 *     paramType="query",

 *     type="string",

 *     defaultValue="vps,os_template"

 *    )

 *   )

 *  )

 * )

 */

 class VpsController extends Controller

 {

     // ...

 }

每次改动API代码注释之后都要手动生成json文件? 太麻烦了, 写了个controller, 每次访问swagger-ui的这个controller, 先生成json再跳转到ui页面。

$b2broot = Yii::getAlias('@b2broot');

$swagger = \Swagger\scan($b2broot.'/myapi');

$json_file = $b2broot.'/swagger-docs/swagger.json';

$is_write = file_put_contents($json_file, $swagger);

if ($is_write == true) {

   $this->redirect('http//localhost/yii2/swagger-ui/dist/index.html');

}

参考文档：
https://www.cnblogs.com/handongyu/p/6992367.html