Yii+swagger-php生成api文档

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  * @OA\Swagger(
 4  * schemes={"http"},
 5  * host="127.0.0.1:80",
 6  * basePath="/",
 7  * consumes={"multipart/form-data"},
 8  * produces={"application/json"},
 9  *
10  * @OA\Info(
11  * version="2.0.0",
12  * title="企微管家接口文档",
13  * description="Version: 2.0.0",
14  * @OA\Contact(
15  *     name="张三",
16  *     url="https://www.baidu.com",
17  *     email="100****975@qq.com"
18  * )
19  * ),
20  * @OA\server(
21  *      url="http://api.exshare.com",
22  *      description="hxq-开发环境",
23  * )
24  * @OA\server(
25  *      url="http://mysaas.com",
26  *      description="开发环境",
27  * )
28  * @OA\server(
29  *      url="http://fcapi.guodong.com",
30  *      description="开发环境",
31  * )
32  * @OA\server(
33  *      url="https://api.365fengchao.com",
34  *      description="正式环境",
35  * )
36  */

    文件/图片的上传比较特殊，oepnApi3.0关于文件上传的说明，官方文档里面讲得不太清楚，尝试了各种办法都不行，最后放到requestbody就可以了

 1  * @OA\Post(
 2  *     tags={"poster"},
 3  *     path="/api/qcloud/upload",
 4  *     summary="保存图片",
 5  *     description="保存图片",
 6  *     @OA\Parameter(
 7  *          name="token",
 8  *          required=true,
 9  *          in="header",
10  *          description="token",
11  *          @OA\Schema(type="string")
12  *     ),
13  *     @OA\RequestBody(
14  *          @OA\MediaType(
15  *              mediaType="multipart/form-data",
16  *              @OA\Schema(
17  *                  required={"weapp_id","plat_group","group","picture"},
18  *                  @OA\Property( property="weapp_id",type="integer",description="应用ID"),
19  *                  @OA\Property( property="plat_group",type="integer",default="poster",description="对象存储图片分组"),
20  *                  @OA\Property( property="group",type="integer",default="poster",description="对象存储分组"),
21  *                  @OA\Property( property="picture", type="file", description="上传文件")
22  *               ),
23  *           )
24  *     ),
25  *     @OA\Response(
26  *         response=200,
27  *         description="",
28  *         @OA\MediaType(
29  *             mediaType="application/json",
30  *             @OA\Schema(
31  *              @OA\Property( property="code",type="integer",description="返回码"),
32  *              @OA\Property( property="message",type="string",description="返回信息"),
33  *              @OA\Property( 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 api\controllers;
 4 
 5 use api\models\Goods;
 6 use common\jsonxml\JsonResponse;
 7 use yii\rest\ActiveController;
 8 use yii\web\Response;
 9 use Yii;
10 class GoodsController extends ActiveController
11 {
12     public $modelClass = 'api\models\Goods';
13     public function actionSwagger()
14     {
15         try {
16             $projectRoot = \Yii::getAlias('@api');//common bootstrap中已配置
17             $swagger = \OpenApi\scan($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

 

posted @ 2020-08-17 14:08  欢乐豆123  阅读(872)  评论(0)  编辑  收藏  举报