CodeIgniter+swagger实现 生成 PHP restful API 自动生成接口文档

一、安装swagger

1、首先需要有composer，没有的自行百度安装

2、下载swagger，打开网站https://packagist.org/packages/zircote/swagger-php，根据自己的php版本选择对应的版本号

3、安装：PhpStorm打开项目，然后在左下角

点击Terminal弹窗黑窗口然后在里面输入：composter require zircote/swagger-php 2.0.13    回车，开始安装

4、使用，安装成功后，在CodeIgniter控制器中(application\controllers\)新建Swagger.php

<?php
/**
 * Created by PhpStorm.
 * User: 50364
 * Date: 2018/12/20
 * Time: 13:44
 * api 接口文档
 */

class Swagger extends CI_Controller {

    /**
     * 构造函数
     *
     * 数据模型，扩展库，辅助方法初始化
     */
    public function __construct() {
        parent::__construct();
    }

    public function index(){
        //接口php文件存放路径
        $openapi = \swagger\scan(SITE_PATH.'front');
        //最后生成的json文件存放路径
        $jasonFile = FILE_FILE.'swagger/swagger-docs/swagger.json';
        //每次自动生成json文件
        file_put_contents($jasonFile,$openapi);
        //加载视图
        $this->load->view('swagger','');
    }
}

然后创建视图文件（application\views\swagger.php）,这里要下载（swagger-ui-master.zip，解压到相应目录，然后把dist中的index.html文件中的内容复制到swagger.php中，再把json文件路径改成自己的就可以），这样每次修改api接口注释信息的时候就会自动生成json文件

  var url = "<?php echo SITE_FILE; ?>swagger/swagger-docs/swagger.json";

二、使用swagger

可以参考这篇博客内容写的还是比较全的（https://laravel-china.org/index.php/topics/7430/how-to-write-api-documents-based-on-swagger-php）

我这简单介绍下：

1、API 描述信息

 * @SWG\Swagger(
 *     swagger="2.0",schemes={"https"},host="api.aa.com",basePath="/api",
 *     @SWG\Info(version="2.0",title="官网接口文档",description="官网2.0版本内部口文档")
 *     )

2、GIT提交

     * @SWG\Get(
     *     path="/product/menu/id/{id}",
     *     summary="产品类别列表接口",
     *     description="返回包含产品类别列表数据信息。",
     *     tags={"product"},
     *     @SWG\Parameter(
     *          name="id",
     *          in="path",
     *          default="5037",
     *          required=true,
     *          description="产品类别id",
     *          type="number"),
     *     @SWG\Response(response=200,description="OK")
     * )

3、Post提交

 * @SWG\Post(
     *     path="/product/product_select",
     *     summary="产品选型接口",
     *     description="返回包含产品选型数据。",
     *     consumes={"application/x-www-form-urlencoded"},
     *     tags={"product"},
     *     @SWG\Parameter(
     *          name="id",
     *          in="formData",
     *          required=true,
     *          default="5037",
     *          description="产品栏目id",
     *          type="number"),
     *       @SWG\Parameter(
     *          name="type",
     *          in="formData",
     *          required=true,
     *          default="1",
     *          description="产品类型 0普通 1小众 2特殊 3与普通二级类别不同",
     *          type="number"),
     *       @SWG\Parameter(
     *          name="child",
     *          in="formData",
     *          default="5077",
     *          description="产品下级栏目id",
     *          type="number"),
     *      @SWG\Parameter(
     *          name="searchIds",
     *          in="formData",
     *          required=false,
     *          description="选型数据:10951,10961,10971",
     *          default="",
     *          type="string"
     *      ),
     *     @SWG\Response(response=200,description="OK")
     * )