swagger-REST API
swagger简介
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里的位置写成自己的项目地址
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://XXXX/doc/swagger.json";
}
hljs.configure({
highlightSizeThreshold: 5000
});
到此位置我们的ui已经配置完了。
第二步：生成环境搭建
下载swagger-php后，进入此文件夹，使用composer下载swagger-php下载swagger-php所需要的依赖，使用命令行，输入（前提是安装了composer）：
composer update
这样后台就算完成了搭建，我们的swagger-php多了vender文件夹
第三步：代码注解
在我们的controller models的文件中编写注解
控制器注释
/**
* @SWG\Get(path="/user/login", 请求路径
* tags={"user"}, 标签
* summary="用户登录", 概要
* description="用户手机号登录", 描述
* operationId="loginUser", 此ID必须在API中描述的所有操作中是唯一的
* produces={"application/xml", "application/json"},
* @SWG\Parameter( 参数列表
* name="mobile", 参数名
* in="query", 1表单参数 formData 2查询参数 query 3路径参数 path 4头参数 header
* description="用户的手机号", 描述
* default="137********", 默认值
* required=false, 是否必填
* type="string" 数据类型
* ),
* @SWG\Parameter(
* name="code",
* in="query",
* description="用户的手机号验证码",
* default="456789",
* required=false,
* type="string"
* ),
* @SWG\Response( 返回状态
* response=200,
* description="成功",
* @SWG\Schema(type="string"),
* @SWG\Header(
* header="X-Rate-Limit",
* type="integer",
* format="int32",
* description="calls per hour allowed by the user"
* ),
* @SWG\Header(
* header="X-Expires-After",
* type="string",
* format="date-time",
* description="date in UTC when toekn expires"
* )
* ),
* @SWG\Response(response=400, description="Invalid username/password supplied")
* )
*/
模型注释
/**
* @SWG\Definition(@SWG\Xml(name="User")) 属性定义
*/
class User
{
/**
* @SWG\Property(format="int64")
* @var int
*/
public $id;
/**
* @SWG\Property()
* @var string
*/
public $username;
/**
* @var string
* @SWG\Property()
*/
public $password;
/**
* @var string
* @SWG\Property()
*/
public $phone;
}
更多了解查看 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
$swagger = \Swagger\scan('../app'); api路径
$json_file = "../vendor/zircote/swagger-docs/swagger.json";
$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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
