Swagger for php的使用

swagger简介

Swagger的使用目的是方便优美的呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置,同时对于restful风格接口有更加优雅的展示, 前端直接看这个Swagger UI就可以, 方便项目管理和团队协作.。

swagger搭建过程

swagger主要分为两个部分,swagger-ui和swagger-php,ui用于展示,后者用于生成相关api。

首先,在自己项目的合理位置上下载前端ui和生成的php。放在项目里面是为了保证访问地址和咱们接口地址都在一起,不会是访问时产生跨域问题。

swagger-ui:https://github.com/swagger-api/swagger-ui.git
swagger-php:https://github.com/zircote/swagger-php.git

第一步:ui搭建

在ui里面有个dist文件夹,修改文件夹里面index.html文件,将url里的位置写成自己的项目地址

  1. var url = window.location.search.match(/url=([^&]+)/);
  2. if (url && url.length > 1) {
  3. url = decodeURIComponent(url[1]);
  4. } else {
  5. url = "http://XXXX/doc/swagger.json";
  6. }
  7. hljs.configure({
  8. highlightSizeThreshold: 5000
  9. });

到此位置我们的ui已经配置完了。

第二步:生成环境搭建

下载swagger-php后,进入此文件夹,使用composer下载swagger-php下载swagger-php所需要的依赖,使用命令行,输入(前提是安装了composer):

composer update

这样后台就算完成了搭建,我们的swagger-php多了vender文件夹

第三步:代码注解

在我们的controller models的文件中编写注解
控制器注释

  1. /**
  2. * @SWG\Get(path="/user/login", 请求路径
  3. * tags={"user"}, 标签
  4. * summary="用户登录", 概要
  5. * description="用户手机号登录", 描述
  6. * operationId="loginUser", 此ID必须在API中描述的所有操作中是唯一的
  7. * produces={"application/xml", "application/json"},
  8. * @SWG\Parameter( 参数列表
  9. * name="mobile", 参数名
  10. * in="query", 1表单参数 formData 2查询参数 query 3路径参数 path 4头参数 header
  11. * description="用户的手机号", 描述
  12. * default="137********", 默认值
  13. * required=false, 是否必填
  14. * type="string" 数据类型
  15. * ),
  16. * @SWG\Parameter(
  17. * name="code",
  18. * in="query",
  19. * description="用户的手机号验证码",
  20. * default="456789",
  21. * required=false,
  22. * type="string"
  23. * ),
  24. * @SWG\Response( 返回状态
  25. * response=200,
  26. * description="成功",
  27. * @SWG\Schema(type="string"),
  28. * @SWG\Header(
  29. * header="X-Rate-Limit",
  30. * type="integer",
  31. * format="int32",
  32. * description="calls per hour allowed by the user"
  33. * ),
  34. * @SWG\Header(
  35. * header="X-Expires-After",
  36. * type="string",
  37. * format="date-time",
  38. * description="date in UTC when toekn expires"
  39. * )
  40. * ),
  41. * @SWG\Response(response=400, description="Invalid username/password supplied")
  42. * )
  43. */

模型注释

  1. /**
  2. * @SWG\Definition(@SWG\Xml(name="User")) 属性定义
  3. */
  4. class User
  5. {
  6. /**
  7. * @SWG\Property(format="int64")
  8. * @var int
  9. */
  10. public $id;
  11. /**
  12. * @SWG\Property()
  13. * @var string
  14. */
  15. public $username;
  16. /**
  17. * @var string
  18. * @SWG\Property()
  19. */
  20. public $password;
  21. /**
  22. * @var string
  23. * @SWG\Property()
  24. */
  25. public $phone;
  26. }

更多了解查看 http://bfanger.github.io/swagger-explained/#/parameterObject

第四步:文档生成

第三步也是最重要的一步,生成相关api,生成方式十分简单,只需要在命令行里执行命令

php swagge-php/bin/swagger 接口文件夹 -o 生成的目的文件夹

“-o” 前面代表API源目录, 即你想要生成哪个目录的API文档, 你的项目代码目录. “-o” 后面是生成到哪个path目的文件夹建议写在项目文件夹下,也是为了避免跨域问题。

每次改动API代码注释之后都要手动生成json文件? 太麻烦了, 写了个controller, 每次访问swagger-ui的这个controller

  1. $swagger = \Swagger\scan('../app'); api路径
  2. $json_file = "../vendor/zircote/swagger-docs/swagger.json";
  3. $ss=file_put_contents($json_file, $swagger);

Methods

HTTP协议提供了很多methods来操作数据:

GET: 获取某个资源。

POST: 创建一个新的资源。

PUT: 替换某个已有的资源。

DELETE:删除某个资源。

request Headers

Accept:服务器需要返回什么样的content

If-Modified-Since/If-None-Match:如果客户端提供某个条件,那么当这条件满足时,才返回数据,否则返回304 not modified。比如客户端已经缓存了某个数据,它只是想看看有没有新的数据时,会用这两个header之一,服务器如果不理不睬,依旧做足全套功课,返回200 ok,那就既不专业,也不高效了。

If-Match:在对某个资源做PUT/DELETE操作时,服务器应该要求客户端提供If-Match头,只有客户端提供的Etag与服务器对应资源的Etag一致,才进行操作,否则返回412 precondition failed。

Response Headers

date:消息发送的时间
server:包含处理请求的原始服务器的软件信息
content-type :接收方指示实体的介质类型
expires:缓存过期时间

Status Codes

200 OK - [GET]:服务器成功返回用户请求的数据。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - []:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作。
401 Unauthorized - [
]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [
]:用户发出的请求针对的是不存在的记录,服务器没有进行操作。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。