前言
程序员最怕写接口文档,以前的项目中都是手工写,然后公布在一个内部网址上,程序参数一修改,接口文档再手工更新一次,很费神,有了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写入失败!';
}
}
}
以上代码中调用了\Swagger\scan(),这个类需要自动加载,我们在入口文件中引入自动加载文件:
require './Tools/vendor/autoload.php';
到此便大功告成,我们可以通过网址访问查看最新的接口文档:http://www.xxx.com/api/index/doc
我们还需要在工作之余学习Swagger的注释写法(可以去这里逛逛editor.swagger.io),尽管麻烦了些,但工欲善其事,必先利其器,往后的项目接口文档变得一劳永逸!