• 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  * @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

     

  • 相关阅读:
    QT 应用程序关闭某个窗口时,关闭打开的所有其他窗口并退出程序 【转】
    XP配置DCOM服务【转】
    Android最佳性能实践(二)——分析内存的使用情况
    Android最佳性能实践(一)——合理管理内存
    快速实现 ListView下拉,图片放大刷新操作
    Android布局实现圆角边框
    android 自定义文字跑马灯 支持拖拽,按住停止滚动,自定义速度
    Android NDK 环境搭建 + 测试例程
    Android -- 桌面悬浮,仿360
    android-async-http AsyncHttpClient介绍
  • 原文地址:https://www.cnblogs.com/hld123/p/13517305.html
Copyright © 2020-2023  润新知