什么是Swagger
Swagger是一种简单、强大的RESTful API表现形式。
其拥有地球上最大的API工具生态环境,无数程序员在几乎所有主流语言和开发环境中添加了对Swagger的支持。
只要你的API添加对Swagger的支持,你就等于拥有了可交互的API文档,SDK代码生成以及外部使用友好的API。
写了这么一堆貌似很屌的话,所以……Swagger
到底是个啥?
其实和官网高度概括的描述一样,Swagger
是一种通用的、和编程语言无关的API的描述规范。只要开发者在自己的API之上添加符合Swagger
规范的描述,就能利用上Swagger
丰富的生态,找到符合自己开发语言的工具去做很多事:比如最常用的生成API文档,或者生成返回假数据的服务端基础代码等等。
说通俗点就是:平时写app接口的时候,都是先写接口再去写接口文档,有时候想测试接口都是一件很复杂的事情,忙的时候都找不到接口文档在什么地方。有了这个组件你就不用担心文档找不到、接口不好测试。它可以帮你边写接口的同时边写接口文档并且可以在线调试接口,就是这么安逸。
swagger-ui
这东西咋用呢? 说白了就是安装Swagger套件, 然后php文件代码里写注释, 用Swagger后端程序跑来php文件中提取注释, 生成一个json文件, 再通过Swagger前端来美化,达到展示JSON数据的效果。
前提:必须支持composer安装组件,且你的电脑上已经安装了composer,具体怎么安装composer这里就不详细介绍了,自行百度安装composer,最好把镜像换成国内的,如果你有很好的vpn等于我没说哈,这些方法百度上都有。
第一步:安装swagger-ui前端
下载thinkphp 框架解压后放到网站根目录中改名tp
git clone https://github.com/swagger-api/swagger-ui.git
下载完成之后,将文件夹放到你的网站根目录上面,例如我是放在我wamp下面的www目录。
接着找到dist目录, 打开index.html把其中的那一串url改成自己的 比如http://localhost/tp/swagger-docs/swagger.json
注意这个url就是后面swagger.json 的路径;
如果你想支持中文在index.html中加上
<script src='lang/translator.js' type='text/javascript'> </script><script src='lang/zh-cn.js' type='text/javascript'></script>
然后打开URL输入http://localhost/swagger-ui/dist/index.html
就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用。swagger.json我是放在tp框架下的swagger-docs目录中的,具体路径看你自己,具体下面会提到,不要慌O(∩_∩)O~。
第二步:安装swagger-php后端
进入你的项目目录执行如下命令:
composer require zircote/swagger-php
提示安装完成后会在你tp项目的vendor中生成一个zircote的组件文件夹,说明已经安装插件成功了。
第三步:生成swagger.json文件
方法1、直接在命令行中输入:
php E:/wamp/www/tp/vendor/zircote/swagger-php/bin/swagger E:/wamp/www/tp/app/controller/ -o E:/wamp/www/tp/public
注意:第一个路径是你安装成功后组件的路径; 第二个路径是你想要生成这个目录下所有用swagger方式注释的php文件,把所有注释生成api文档; 第三个路径是你存放生成swagger.json的路径
方法2、编写控制器方法生成swagger.json:
如果我们每次修改了api,还要手动执行第三步的代码,有些繁琐,那我们就在控制器中写一个方法,每次访问swagger-ui的时候自动执行,然后跳转到前台swagger界面中。
下面是控制器里面的方法
$path = '../application'; //你想要哪个文件夹下面的注释生成对应的API文档
$swagger = \Swagger\scan($path);
//header('Content-Type: application/json');
//echo $swagger;
$swagger_json_path = $path.'/swagger-docs/swagger.json';
$res = file_put_contents($swagger_path, $swagger);
if ($res == true) {
$this->redirect('http://localhost/swagger-ui/dist/index.html');
}
第四步:编写swagger注释
控制器的注释写法
/** * @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 { // ... }
这只是个简单的实例具体的注释写法请自己百度
到此完成了,具体swagger-php的注释使用方法,请打开安装好的组件目录