Swagger 是一个简单但功能强大的 API 表达工具。值得感激的是，Swagger 的源码 100% 开源在 github。
官方网站: http://swagger.io/
1、定义一个 API 操作
<?php
/**
* @SWG\Swagger(
* swagger=”2.0″
* schemes={“https”},
* host=”tcmapi.emao.com”,
* basePath=”/v1.0″,
* @SWG\Info(version=”1.0.0″, title=”淘车猫 Api 文档”,description=”淘车猫 Api 文档”)
* )
* @SWG\Get(
* path=”/persons”,
* summary=”获取一些人”,
* description=”返回包含所有人的列表。”,
* @SWG\Response(
* response=200,
* description=”一个用户列表”,
* @SWG\Schema(
* type=”array”,
* @SWG\Items(
* required={“username”}
* @SWG\Properties()
* )
* ),
* ),
* )
*/
query parameteers 请求参数
<?php
/**
* @SWG\Get(
* path=”/persons”,
* summary=”获取一些人”,
* description=”返回包含所有人的列表。”,
* @SWG\Parameter(name=”pageSize”,in=”query”, description=”Number of persons returned”,type=”integer”),
* @SWG\Parameter(name=”pageNumber”, in=”query”,description=”Page number”, type=”integer”)
* )
*/
response 响应类型
对于每个方法（或操作），我们都可以在响应 (responses) 中添加任意的 HTTP状态码（比如 200 OK 或者 404 Not Found 等）。这个例子中我们添加上 200 的响应：
<?php
/**
* @SWG\Response(response=200, description=”一个用户列表”)
*/
响应内容
接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个 string 类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
<?php
/**
* @SWG\Schema(
* type=”array”,
* @SWG\Items(
* required={“username”},
* @SWG\Property(property=”firstName”,type=”string”,description=”firstName” ),
* @SWG\Property(property=”lastName”,type=”string”,description=”lastName”),
* @SWG\Property(property=”username”,type=”string”,description=”username”)
* )
* )
*/
test.php
<?php
/**
* @SWG\Swagger(
* @SWG\Info(
* title=”API文档”,version=”版本1.0″,description=”本文档仅限于测试”
* )
* ) */
class Test extends Controller
{
/**
* @SWG\Post(
* path=”/index/test/getstudent”,
* tags={“后台管理”},
* summary=”更新用户的信息”,
* description=”传入用户的id为参数”,
* @SWG\Parameter(name=”id”, type=”integer”, in=”formData”, description=”学生id”,required=true),
* @SWG\Response(response=”200″, description=”请求成功”),
* @SWG\Response(response=”201″, description=”请求失败”)
* )
*/
public function getstudent(Request $request)
{
$id = input(‘id’);
$res = Db::name(‘student’)->where(‘id’,$id)->select();
if ($res) {
return json_encode([‘code’=>200,’msg’=>’查询成功’]);
} else {
return json_encode([‘code’=>201,’msg’=>’查询失败’]);
}
}
}