Yii+swagger-php生成api文档
概述
swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，通过它可以优美地呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置, 前端通过swagger-ui就可以直接看, 方便项目管理和团队协作。
使用
安装swagger-php组件后, 然后在API代码里写注释, 用swagger后端程序跑API来提取注释, 生成一个json文件, 再通过swagger前端(swagger-ui)来美化,整理JSON数据。这里记录下在Yii2.0 advanced版本中整合swagger相关组件来生成api文档的过程。
1、安装
1）用composer下载swagger-php
composer require zircote/swagger-php:3.0.4
2）从GitHub上下载swagger-ui最新版本
将下载的文件重名为swagger-ui，放在/api/web目录下
3）在api/web下面新建文件夹swagger-docs,然后在swagger-docs中新建文件 swagger.json， 如下图
4）修改swagger-ui/dist/index.html 2处注释地方，如下图
说明：swagger-ui 其实是一个独立的UI，也可以理解为前端页面，而咱们下载的swagger-php负责接口注释的解析，它俩中间需要通过swagger.json来关联。
2、写注释
注释完全可以单独写一个文档，并非非要写在接口上,不管写在哪，只要被扫到即可。比如这里我写到api/controllers/swagger.php
1 <?php 2 /** 3 * @OASwagger( 4 * schemes={"http"}, 5 * host="127.0.0.1:80", 6 * basePath="/", 7 * consumes={"multipart/form-data"}, 8 * produces={"application/json"}, 9 * 10 * @OAInfo( 11 * version="2.0.0", 12 * title="企微管家接口文档", 13 * description="Version: 2.0.0", 14 * @OAContact( 15 * name="张三", 16 * url="https://www.baidu.com", 17 * email="100****975@qq.com" 18 * ) 19 * ), 20 * @OAserver( 21 * url="http://api.exshare.com", 22 * description="hxq-开发环境", 23 * ) 24 * @OAserver( 25 * url="http://mysaas.com", 26 * description="开发环境", 27 * ) 28 * @OAserver( 29 * url="http://fcapi.guodong.com", 30 * description="开发环境", 31 * ) 32 * @OAserver( 33 * url="https://api.365fengchao.com", 34 * description="正式环境", 35 * ) 36 */
文件/图片的上传比较特殊，oepnApi3.0关于文件上传的说明，官方文档里面讲得不太清楚，尝试了各种办法都不行，最后放到requestbody就可以了
1 * @OAPost( 2 * tags={"poster"}, 3 * path="/api/qcloud/upload", 4 * summary="保存图片", 5 * description="保存图片", 6 * @OAParameter( 7 * name="token", 8 * required=true, 9 * in="header", 10 * description="token", 11 * @OASchema(type="string") 12 * ), 13 * @OARequestBody( 14 * @OAMediaType( 15 * mediaType="multipart/form-data", 16 * @OASchema( 17 * required={"weapp_id","plat_group","group","picture"}, 18 * @OAProperty( property="weapp_id",type="integer",description="应用ID"), 19 * @OAProperty( property="plat_group",type="integer",default="poster",description="对象存储图片分组"), 20 * @OAProperty( property="group",type="integer",default="poster",description="对象存储分组"), 21 * @OAProperty( property="picture", type="file", description="上传文件") 22 * ), 23 * ) 24 * ), 25 * @OAResponse( 26 * response=200, 27 * description="", 28 * @OAMediaType( 29 * mediaType="application/json", 30 * @OASchema( 31 * @OAProperty( property="code",type="integer",description="返回码"), 32 * @OAProperty( property="message",type="string",description="返回信息"), 33 * @OAProperty( property="data",type="json",description="返回数据"), 34 * example={ 35 * "code": 0, 36 * "message": "上传成功", 37 * "data": { 38 * "url": "https://wxmiimage.esharex.com/test/fengchao/poster/15982644936091.png" 39 * } 40 * } 41 * ) 42 * ) 43 * ), 44 * ),
3、生成json
与java不同，php需要写完接口，运行程序，然后自己生成swagger.json文件才行。也就是一长串命令行，太麻烦了。就不写了。
这里写了一个控制器/方法，直接访问方法名获取最新信息写入到swagger.json里，然后在重定向到页面，如图:
1 <?php 2 3 namespace apicontrollers; 4 5 use apimodelsGoods; 6 use commonjsonxmlJsonResponse; 7 use yii estActiveController; 8 use yiiwebResponse; 9 use Yii; 10 class GoodsController extends ActiveController 11 { 12 public $modelClass = 'apimodelsGoods'; 13 public function actionSwagger() 14 { 15 try { 16 $projectRoot = Yii::getAlias('@api');//common bootstrap中已配置 17 $swagger = OpenApiscan($projectRoot);//扫描需要生成接口文档的目录，此时真正读取注释生成数组对象中 18 $swagger = json_encode($swagger) ;;//转成json 19 $json_file = $projectRoot . '/web/swagger-docs/swagger.json';//生成json文件路径 20 $is_write = file_put_contents($json_file, $swagger);//写入json文件 21 if ($is_write == true) { 22 $this->redirect('/swagger-ui/dist/index.html');//跳转接口文档页面 23 } 24 25 //不建议暴露此接口给接口使用人。使用者直接看生成好的文档即可：http：//xxxx.com/swagger-ui/dist/index.html 26 27 }catch(Exception $e){ 28 Yii::error($e->getMessage()); 29 return false; 30 } 31 32 } 33 34 }
4、然后通过swagger-ui展示
然后在上面的文档中可以输入要求的参数，在线测试接口
参考链接：
https://blog.csdn.net/gufengbiaoying/article/details/107022717
https://xiaoxiami.gitbook.io/swagger/swagger-php-wen-dang/openapi-gui-fan