一、安装swagger
1、首先需要有composer,没有的自行百度安装
2、下载swagger,打开网站/packages/zircote/swagger-php,根据自己的php版本选择对应的版本号
3、安装:PhpStorm打开项目,然后在左下角
点击Terminal弹窗黑窗口
然后在里面输入:composter requirezircote/swagger-php2.0.13 回车,开始安装
4、使用,安装成功后,在CodeIgniter控制器中(/admin/application/controllers/)新建Swagger.php
/**
* Created by PhpStorm.
* User: 50364
* Date: /12/20
* Time: 13:44
* api 接口文档
*/
class Swagger extends CI_Controller {
/**
* 构造函数
*
* 数据模型,扩展库,辅助方法初始化
*/
public function __construct() {
parent::__construct();
}
public function index(){
//接口php文件存放的本地路径 要找到入口文件index.php的路径 (D:/www/ci)
$openapi = swagger\scan(__DIR__);
//最后生成的json文件存放路径(例子:D:/www/ci/swagger/swagger-docs/swagger.json)
$jasonFile = __DIR__.'swagger/swagger-docs/swagger.json';
//每次自动生成json文件
file_put_contents($jasonFile,$openapi);
//加载视图
$this->load->view('swagger','');
}
}
然后创建视图文件(/admin/application/controllers/swagger.php),这里要下载(swagger-ui-master.zip,解压到相应目录,然后把dist中的index.html文件中的内容复制到swagger.php中,再把json文件路径改成自己的就可以),这样每次修改api接口注释信息的时候就会自动生成json文件
路径: 域名/swagger/swagger-docs/swagger.json
var url = "<?php echo SITE_FILE; ?>swagger/swagger-docs/swagger.json";
二、使用swagger
可以参考这篇博客内容写的还是比较全的(https://laravel-/index.php/topics/7430/how-to-write-api-documents-based-on-swagger-php)
我这简单介绍下:
1、在接口控制器目录下创建/api/application/controllers/swagger.php,写API 描述信息
/*
* @SWG\Swagger(
* swagger="2.0",schemes={"https"},host="",basePath="/api",
* @SWG\Info(version="2.0",title="官网接口文档",description="官网2.0版本内部口文档")
* )
*/
2、在其他接口文件GIT提交
class Product ectends restful{
/*
* @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")
* )
*/
public menu_get(){
}
}
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")
* )