swagger在thinkphp6的使用方式
以下以thinkphp6框架及dev.think.com项目域名进行示范:下载swagger-uigit clone https://github.com/webjars/swagger-ui.git复制swagger-ui目录下dist文件到php项目根目录如:thinkphp6的public目录下打开php项目安装swagger-php拓展composer require z...
·
以下以thinkphp6框架及dev.think.com项目域名进行示范:
下载swagger-ui
git clone https://github.com/swagger-api/swagger-ui.git
复制swagger-ui目录下dist文件到php项目根目录
如:thinkphp6的public目录下
打开php项目安装swagger-php拓展
composer require zircote/swagger-php
编写文档接口
<?php
use think\facade\Route;
Route::get('/swagger', function() {
$openapi = \OpenApi\scan('../app');
header('Content-Type: application/json');
echo $openapi->toJson();
});
编辑dist目录下index.html文件,修改url地址为文档路由地址
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "http://dev.think.com/swagger",//路由地址
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
注释格式参考
/**
* @OA\Get(path="/api/article",
* tags={"文章管理"},
* summary="文章列表",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string", default="123456")),
* @OA\Parameter(name="page", in="query", description="页码", @OA\Schema(type="int", default="1")),
* @OA\Parameter(name="limit", in="query", description="行数", @OA\Schema(type="int", default="10")),
* @OA\Response(response="200", description="The User")
* )
*/
public function index()
{
$limit = $this->request->param('limit/d', 10);
$data = ArticleModel::paginate($limit);
return $this->jsonReturn(200, 'success', $data);
}
/**
* @OA\Post(path="/api/article",
* tags={"文章管理"},
* summary="新增文章",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="multipart/form-data",
* @OA\Schema(
* @OA\Property(description="文章名称", property="title", type="string", default="dd"),
* @OA\Property(description="文章内容", property="content", type="string"),
* required={"title", "content"})
* )
* ),
* @OA\Response(response="200", description="successful operation")
* )
*/
public function save()
{
$param = $this->request->post();
$rule = [
'title' => 'require',
'content' => 'require'
];
$param = array_intersect_key($param, $rule);
try {
$this->validate($param, $rule);
} catch (ValidateException $e) {
return $this->jsonReturn(412, $e->getError());
}
ArticleModel::create([
'title' => $param['title'],
'content' => $param['content'],
'created_at' => date('Y-m-d H:i:s')
]);
return $this->jsonReturn();
}
/**
* @OA\Get(path="/api/article/{id}",
* tags={"文章管理"},
* summary="文章详情",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\Parameter(name="id", in="path", description="文章id", @OA\Schema(type="int")),
* @OA\Response(response="200", description="The User")
* )
*/
public function read($id)
{
$data = ArticleModel::whereId($id)->find();
return $this->jsonReturn(200, 'success', $data);
}
/**
* @OA\Put(path="/api/article/{id}",
* tags={"文章管理"},
* summary="编辑文章",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\Parameter(name="id", in="path", description="文章id", @OA\Schema(type="int")),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="content-type/json",
* @OA\Schema(
* @OA\Property(description="文章名称", property="title", type="string"),
* @OA\Property(description="文章内容", property="content", type="string"),
* required={"title", "content"})
* )
* ),
* @OA\Response(response="200", description="successful operation")
* )
*/
public function update($id)
{
$param = $this->request->put();
$rule = [
'title' => 'require',
'content' => 'require'
];
$param = array_intersect_key($param, $rule);
try {
$this->validate($param, $rule);
} catch (ValidateException $e) {
return $this->jsonReturn(412, $e->getError());
}
ArticleModel::whereId($id)->update([
'title' => $param['title'],
'content' => $param['content'],
'updated_at' => date('Y-m-d H:i:s')
]);
return $this->jsonReturn();
}
/**
* @OA\Delete(path="/api/article/{id}",
* tags={"文章管理"},
* summary="删除文章",
* @OA\Parameter(name="token", in="header", description="token", @OA\Schema(type="string")),
* @OA\Parameter(name="id", in="path", description="文章id", @OA\Schema(type="int")),
* @OA\Response(response="200", description="The User")
* )
*/
public function delete($id)
{
ArticleModel::destroy($id);
return $this->jsonReturn();
}
PUT、POST请求方式的注释格式不一样
Paramter参数的in参数
1、header:参数在header头中传递
2、query:参数在地址后传递如 test.com?id=1
3、path:参数在rest地址中如 test.com/user/1
4、cookie:参数在cookie中传递
Schema配置
1、type:指定字段类型
2、default:指定字段默认值
更多使用方式参考php项目中vendor中zircote\swagger-php目录下的Examples文件
访问http://dev.think.com/dist/既可使用swagger
开放原子开发者工作坊旨在鼓励更多人参与开源活动,与志同道合的开发者们相互交流开发经验、分享开发心得、获取前沿技术趋势。工作坊有多种形式的开发者活动,如meetup、训练营等,主打技术交流,干货满满,真诚地邀请各位开发者共同参与!
更多推荐
已为社区贡献2条内容
所有评论(0)