PHP与 RESTful风格的swagger结合生成API

版权声明：本文为博主原创文章，未经博主允许不得转载。

1. 什么是RESTful风格

1.官方解释：
一种软件架构风格，设计风格而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。（好吧！官方就是官方，果然听不懂～）
2.别人靠谱的理解:
是通过具体的URI定位符，找到对应的资源，然后以固定的格式返回数据，这样的才是Restful API；
3.我的理解:
既然叫风格，所见及风格。通过不同颜色区分不同的url请求，并通过URL定位去请求后台对应的资源并返回相应的数据格式。

2.为什么用RESTful风格开发接口呢

1.无状态，这点非常重要。在调用一个接口（访问、操作资源）的时候，可以不用考虑上下文，不用考虑当前状态，极大的降低了复杂度。（这句话感觉很经典，直接引用知乎上的这句）。
2.每一个URI代表一种资源，就像面向对象语言一切都是对象一样，RESTful API一切都是资源。通过请求某一个url就能获取到你想要的东西。
3.所见即所得，很美观（自认为，嘿嘿）；

3.为什么选择SWAGGER

1.我之前也用过其他的接口文档，综合来说，跟swagger相比，页面就是丑。你让追求美感的前端攻城狮怎么用。so chose swagger。
哈哈，在下边

支持API自动生成同步的在线文档这些文档可用于项目内部API审核方便测试人员了解API这些文档可作为客户产品文档的一部分进行发布支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度

跟其他API文档工具相比，Swagger各有优缺点，但它功能最多、也是最流行的。

4.废话少说，看效果

怎么样，就是好看。
扯了这么多，下边开始搭建环境。我用thinkphp5给大家搭建一个测试案例，会一步一步从头开始。

5.测试案例

第一步
请大家先将TP5框架搭建完成，这个自己上TP官网上自己搞。
第二部
从swagger官网或者github上下载两个文件swagger-ui,swagger-php，将这两个文件整合到TP5框架里，效果如如下：

直接扔到根目录下就可以。
第三部
修改swagger-ui下dist下index.html里边的url，需要指向你的代码经过swagger-php转化成json后所存放的文件。我的代码经过转化后放在了swagger-php下的docs文件夹下的swagger.json文件里了。swagger.json也是随便起的名字，只要存放的是json文件就行。
1.swagger-php的作用就是将固定格式的php代码转化生成swagger-ui能够读懂的json文件。
2.所有的接口文件都要转化成swagger-ui能够读取的json形式才能够生成好看的接口文档。（你有一万个接口，都会生成json文件存放到这个swagger.json文件里）。

这个json文件swagger-ui才能读取，并生成好看的界面。
到这一步，你还无法生成json文件，需要一个入口文件。这个入口文件就在swagger-php的demo里。

将这个入口文件稍加改造

我在下边新创建了一个模块，你们用自带的index都行，然后我又创建了一个文件夹，然后给这个入口文件改了一个名字，叫compile_enter.php（编译入口）,其实直接把他扔进模块文件夹里就行，不用这么麻烦，只要扫描该模块下有这个入口文件就行，主要怕看着乱。host改成你的域名，basepath拼接上访问路径/public/模块名

<?php/** * @SWG\Swagger( *     schemes={"http"}, *     host="www.pretty.com:80", *     basePath="/public/prettyinterface", *     @SWG\Info( *         version="1.0.0", *         title="Swagger Petstore", *         description="This is a sample server Petstore server.  You can find out more about Swagger at <a href=""http://swagger.io"">http://swagger.io</a> or on irc.freenode.net, #swagger.  For this sample, you can use the api key ""special-key"" to test the authorization filters", *         termsOfService="http://helloreverb.com/terms/", *         @SWG\Contact( *             email="[e-mail]" *         ), *         @SWG\License( *             name="Apache 2.0", *             url="http://www.apache.org/licenses/LICENSE-2.0.html" *         ) *     ), *     @SWG\ExternalDocumentation( *         description="Pretty", *         url="http://swagger.io" *     ) * ) */

prettyinterface这是我的模块名。
下边打开cmd命令窗口，进行json文件的编译转换

这个命令分为四个部分，php告诉程序这是用php执行并解析的命令。第二个命令：告诉让swagger-php\bin\swagger来执行解析命令。第三个命令：告诉swagger-php你要扫描的目录，只要入口文件在这个目录下就行。最后一个命令：告诉swagger-php你解析完的命令（就是json文件）写入到哪里。这里生成的json文件也是swagger-ui将要读取并生成页面的json。
好了我这里已经生成了两个接口cmd里也能看到。

当然你生成的是什么也没有，因为你什么也没有写。但是界面能够展示出来了。

第四部
你将自己的接口文件写在模块的Controller下即可，就是TP框架怎么写你就怎么写，但是······注释必须要按照swagger的规范来。
demo（就是swagger-php文件夹下的）里边也有，你也可以看 。规范就是规范必须要按照他的规范来写。

<?phpnamespace app\prettyinterface\controller;use think\Db;/**        * @SWG\Tag(        *   name="Search",        *   description="标签搜索展示套装列表"        * )          */class SearchController extends FatherController{        /**        * @SWG\Post(        *  path="/Search_Controller/CoordinatesList",*  summary="标签搜索套装列表",*  tags={"Search"},*  description="<strong>没有条件默认展示每页10条推荐商品。有条件默认展示10件商品。[id:主键],[coordinates_id:唯一标识],[image:列表图片],[price:售价],[comment_count:评价数],[good_comment:好评率],[tag_names:套装标签],[up:点赞数],[down:踩数],[recommend:是否推荐0不推荐1推荐]</strong>",*  consumes={ "application/x-www-form-urlencoded"},*  produces={ "application/json"},*  operationId="SearchCoordinatesListPost",     *     @SWG\Parameter(     *         name="search",     *         in="formData",     *         description="标签集合(1，1&2&3)",     *         required=false,          *   type="string",     *         collectionFormat="csv"     *     ),     *     @SWG\Parameter(     *         name="page",     *         in="formData",     *         description="当前页码(默认为1)",     *         required=false,          *   type="integer",     *         collectionFormat="csv"     *     ),     *     @SWG\Parameter(     *         name="pages",     *         in="formData",     *         description="每页显示数据量(默认为10)",     *         required=false,          *   type="integer",     *         collectionFormat="csv"     *     ),     *     @SWG\Response(     *         response=200,     *         description="josn格式数据<strong>(0请求成功;>0请求有误;Totle总数据量;Pre_page当前页码;Pages每页数据量)</strong>",     *         @SWG\Schema(     *       ref="#/definitions/ApiResponse"     *     ))        * )        */       public function CoordinatesList()    {

之前入口文件的host拼上basepath在拼上这里的path正好组成了一个完整的url这样他才能找到你的后台接口。想想也不是很神奇。TP5方法名用驼峰需要加下划线如：Search_Controller。

后注：我这个swagger的介绍也就是比别人详细一些，而且swagger需要写这么麻烦的注释也省事不到哪里去呀～SO，我这还有不需要这么麻烦的注释也能达到相同的效果，就是自己写了正则，将普通注释转换成了这种繁琐的swagger认识的注释
只需写成这样：

<?phpnamespace app\prettyinterface\controller;use think\Db;/** * @desc 标签搜索展示套装列表 * @author 熊童子 */class SearchController extends FatherController{    /**     * @name 标签搜索套装列表     * @desc 没有条件默认展示每页10条推荐商品。有条件默认展示10件商品。[id:主键],[coordinates_id:唯一标识],[image:列表图片],[price:售价],[comment_count:评价数],[good_comment:好评率],[tag_names:套装标签],[up:点赞数],[down:踩数],[recommend:是否推荐0不推荐1推荐]     * @method Post     * @param string search null 标签集合(1，1&2&3)     * @param integer page null 当前页码(默认为1)     * @param integer pages null 每页显示数据量(默认为10)     * @return josn格式数据     */    public function CoordinatesList()    {

结果：