php与swagger3自定义,利用yii2和swagger打造完美的RestFul Api接口

本文将按照完全真实的操作流程进行写作！技术人员照着此文，可以直接搭建一个yii2和swagger结合的RestFul风格的API接口平台！

第一步：本地搭建yii2项目(以basic基础项目为准)

php composer.phar create-project yiisoft/yii2-app-basic basic -vvv

运行以上命令，用composer安装的方式，在本地搭建一个yii2项目。(安装composer和本地站点配置这里就不作细述了)

比如我们的项目地址为：yii2basic.my.com

第二步：下载yii2-swagger包

php composer.phar require --prefer-dist light/yii2-swagger "~1.0.4" -vvv

第三步：准备工作

为了后面swagger的使用能按照设想顺利进行，我们在这个地方先做好几项准备工作

1、url美化。我们不希望url在访问时，还需要输入index.php这样的结构，而是希望直接访问 控制器名/方法名 这样的结构，所以，我们需要配置：

config下面的web.php里面的components组件：

'urlManager' => [

'enablePrettyUrl' => true,

'showScriptName' => false,

'rules' => require(__DIR__ . '/route.php'),

],

顺带着，我们还在config目录下新建一个route.php文件，专用用来存放路由。这个文件怎么写？最后给个参考！

2、输出格式化。接口的目的就是return回信息的，我们需要配置返回信息的格式默认都是json格式。

config下面的web.php里面的components组件：

'response' => [

'format' => 'json'

],

3、新建一个module专门用来写API接口(当然，并不是必须要新建一个模块，但是新建一个单独的模块，更清晰更好管理)

我们直接用gii来新建：

浏览器访问http://yii2basic.my.com/gii

进入页面-》选择Module Generator-》

好，做完这三步，现在我们的准备工作基本好了！

第四步：建立swagger的入口文件和信息文件

我们在项目的controllers目录下新建一个与默认的SiteController.php同级的SwaggerControll.php文件

swagger还需要一个配置文件，才能保证在读取信息时，不出错。因为，上图中，我们只让swagger到v1下面的controllers下面去扫描。所以，我们就把swagger的配置文件放在v1/controllers下面，取名swagger.php

现在，你访问http://yii2basic.my.com/swagger 这个链接，就能看到swagger的接口页面了。只是，我们现在还没有写接口。好，那我们现在就开始写一个接口来看看。

第五步、开始写接口并且为每个接口做路由配置

还是上面说的，我们只配置了swagger扫描api/controllers这个目录下的文件。所以，我们还是把接口文件写在api/controllers目录下。

就举例叫UserController.php

现在，我们接口也写好了，按道理是可以访问的了，但是我们还需要配置下路由，以便更加健壮和兼容性好！还记得，我上面说的那个顺带在config目录下建立的route.php文件吧。现在开始写它！

好，现在，我们可以再Swagger的界面，直接操作接口了！

举报/反馈