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

原创 2017年07月18日 17:45:55

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="apiteam@wordnik.com"
 *         ),
 *         @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文件夹下的)里边也有,你也可以看 。规范就是规范必须要按照他的规范来写。

<?php
namespace 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认识的注释
只需写成这样:

<?php
namespace 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()
    {

这里写图片描述

结果:
这里写图片描述

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

在Spring中使用Springfox和swagger生成restful风格的API文档

发现一位博主写的特别棒 强烈推荐参考他的:大牛的网址由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建R...

swagger 生成 PHP restful API 接口文档

需求: 为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用 swagger 前手写文档的血泪史. 我的故事却又不同,因为首先来说,我在公司是 Android 组负责人,属于上述血泪史中...

swagger整合SpringMvc生成Restful api

  • 2017年07月05日 10:34
  • 14.13MB
  • 下载

Swagger集成Springboot生成Restful api

前言Spring Boot是目前最流行的微服务框架,Spring Boot让我们的Spring应用变的更轻量化。比如:你可以仅仅依靠一个Java类来运行一个Spring引用。你也可以打包你的应用为ja...
  • zjx2016
  • zjx2016
  • 2017年07月05日 12:22
  • 1280

Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档

在App后端开发中经常需要对移动客户端(Android、iOS)提供RESTful API接口,在后期版本快速迭代的过程中,修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,...
  • FX_SKY
  • FX_SKY
  • 2017年01月04日 19:28
  • 4691

SpringBoot中使用Swagger生成RESTful规范API文档

Swagger是为了描述一套标准的而且是和语言无关的REST API的规范。对于外部调用者来说,只需通过Swagger文档即可清楚Server端提供的服务,而不需去阅读源码或接口文档说明。 官方网站...

Spring Boot进阶1 - 整合Swagger2自动生成RESTful API文档

本文将介绍RESTful API可视化调试工具Swagger2,它可以轻松的整合到spring生态链中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的...

使用swagger作为restful api的doc文档生成

初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情。也许多点,也许少点。甚至,接口总是需要适应新需求的,修改了,增加了...

基于PHP SLIM 框架搭建 RESTful 风格API 示例

PHP是快速搭建网站的利器,在中小网站有着广泛的应用。Slim是一个PHP微型框架,可以帮你快速创建强劲的Web应用和API。经常有人讨论说那种PHP框架更好,其实这个问题就像语言本身的争论一样,是没...

Spring Boot Swagger2 构建RESTful API

  • 2016年12月30日 15:31
  • 41KB
  • 下载
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:PHP与 RESTful风格的swagger结合生成API
举报原因:
原因补充:

(最多只允许输入30个字)