如果你要使用表单请求类,那么需要继承 Dingo API 表单请求基类 Dingo\Api\Http\FormRequest 或者完全自己实现。表单请求类会检查输入请求是否是针对当前 API 的,如果是的话,当验证失败会抛出 Dingo\Api\Exception\ValidationHttpException 异常。这个异常会被 Dingo API 渲染并返回相应的错误响应。
应用内部请求 Dingo API
在 API 路由中请求 API
$api->version('v3', function ($api) {
...
$api->get('task/{id}', function ($id) {
$dispatcher = app(\Dingo\Api\Dispatcher::class);
$task = $dispatcher->version('v1')->get('dingoapi/task/' . $id);
dd($task);
});
});
在 Web 路由中请求 API
$dispatcher = app(\Dingo\Api\Dispatcher::class);
Route::get('/task/{id}', function ($id) use ($dispatcher) {
$task = $dispatcher->version('v3')->get('dingoapi/task/' . $id);
dd($task);
});
在已认证 API 路由中请求
在已认证的 API 路由中请求 Dingo API 的认证接口比较简单,不需要做任何额外的操作,因为已经认证的 API 接口中发起内部请求中会自动带上 Authorization 字段。
在未认证或 Web 路由中请求
在未认证 API 路由或 Web 路由中对 Dingo API 认证接口发起内部请求需要将访问令牌设置到请求头 Authorization 字段中才可以,我们以之前待办任务列表中的 home 路由为例,这是一个 Web 路由,虽然需要认证才能访问,但是 Web 路由认证和 API 路由认证走的是两套体系,之间并不相通,内部请求 的 API 接口需要单独认证,这里我们借助 Passport 私人访问令牌来实现该 API 接口的认证,打开 app/Http/Controllers/HomeController.php,将 index 方法中获取任务列表的逻辑改为基于 Dingo API v3 版本的 tasks.index 接口获取,该接口是需要认证的,我们通过 Passport 私人访问令牌生成访问令牌,然后将其设置到 Authorization 请求头
publicfunctionindex(Request $request, Dispatcher $dispatcher)
{
$params = [];
if ($request->has('page')) {
$params['page'] = $request->get('page');
}
if ($request->has('limit')) {
$params['limit'] = $request->get('limit');
}
$token = $request->user()->createToken('Internal Request Token')->accessToken;
$tasks = $dispatcher->on('todo.test')->header('Authorization', 'Bearer ' . $token)->version('v3')->get('dingoapi/tasks', $params);
returnview('home', ['tasks' => json_encode($tasks->items())]);
}
try {
app(\Dingo\Api\Dispatcher::class)->with($payload)->post('dingoapi/tasks');
} catch (Symfony\Component\HttpKernel\Exception\ConflictHttpException $e) {
// Do something here, like return with an error.
}
生成 API 文档
# Resource
/**
* Task Resource Controller
* @package App\Http\Controllers\Api
* @Resource("Tasks")
*/
@Resource("Tasks", uri="/tasks")
# Action
/**
* Display a listing of the resource.
* @param Request $request
* @return \Illuminate\Http\Response
* @GET("/{?page,limit}"
*/
/**
* Store a newly created resource in storage.
*
* @param CreateTaskRequest $request
* @return \Illuminate\Http\Response
* @POST("/")
*/
# Version
/**
* Display a listing of the resource.
* @param Request $request
* @return \Illuminate\Http\Response
* @GET("/{?page,limit}"
* @Versions({"v3"})
*/
# Parameter
/**
* Display a listing of the resource.
* @param Request $request
* @return \Illuminate\Http\Response
* @GET("/{?page,limit}")
* @Versions({"v3"})
* @Parameters({
* @Parameter("page", description="page number", type="integer", required=false, default=1),
* @Parameter("limit", description="task item number per page", type="integer", required=false, default=10)
* })
*/
# Request
/**
* Store a newly created resource in storage.
*
* @param CreateTaskRequest $request
* @return \Illuminate\Http\Response
* @POST("/")
* @Versions({"v3"})
* @Request("text=test&is_completed=1", contentType="application/x-www-form-urlencoded")
*/
@Request("text={text}&is_completed={is_completed}", contentType="application/x-www-form-urlencoded", attributes={
@Attribute("text", type="string", required=true, description="the body of task", sample="test task"),
@Attribute("is_completed", type="boolean", required=true, description="task is completed ornot", sample=1)
})
@Request({"text":"test task", "is_completed":1}, attributes={
@Attribute("text", type="string", required=true, description="the body of task", sample="test task"),
@Attribute("is_completed", type="boolean", required=true, description="task is completed ornot", sample=1)
})
@Request({"text":"test task", "is_completed":0}, headers={
"Authorization": "Bearer {API Access Token}"
}, attributes={
@Attribute("text", type="string", required=true, description="the body of task", sample="test task"),
@Attribute("is_completed", type="boolean", required=false, description="task is completed ornot", sample=0)
})
# Response
/**
* Store a newly created resource in storage.
*
* @param CreateTaskRequest $request
* @return \Illuminate\Http\Response
* @POST("/")
* @Versions({"v3"})
* @Request({"text":"test task", "is_completed":0}, headers={
* "Authorization": "Bearer {API Access Token}"
* }, attributes={
* @Attribute("text", type="string", required=true, description="the body of task", sample="test task"),
* @Attribute("is_completed", type="boolean", required=true, description="task is completed ornot", sample=0)
* })
* @Response(200, body={"data":{"id":4,"text":"Test Task 4","completed":"no","link":"http://todo.test/dingoapi/task/4"}})
*/
@Response(200, body={"data":{"id":1,"text":"Test Task 1","completed":"no","link":"http://todo.test/dingoapi/task/1"}}, attributes={
@Attribute("id", type="integer", description="the id of task", sample=1),
@Attribute("text", type="string", description="the body of task", sample="test task"),
@Attribute("completed", type="string", description="task is completed ornot", sample="no"),
@Attribute("link", type="string", description="task link", sample="http://todo.test/dingoapi/task/1")
})
# Transaction
/**
* Update the specified resource in storage.
*
* @param \Illuminate\Http\Request $request
* @param int $id
* @return \Illuminate\Http\Response
* @POST("/{id}")
* @Versions({"v3"})
* @Parameters({
* @Parameter("id", type="integer", description="the ID of the task", required=true)
* })
* @Transaction({
* @Request({"text":"test task", "is_completed":1}, headers={
* "Authorization": "Bearer {API Access Token}"
* }, attributes={
* @Attribute("text", type="string", required=true, description="the body of task", sample="test task"),
* @Attribute("is_completed", type="boolean", required=true, description="task is completed ornot", sample=1)
* }),
* @Response(200, body={"data":{"id":1,"text":"Test Task 1","completed":"no","link":"http://todo.test/dingoapi/task/1"}}, attributes={
* @Attribute("id", type="integer", description="the id of task", sample=1),
* @Attribute("text", type="string", description="the body of task", sample="test task"),
* @Attribute("completed", type="string", description="task is completed ornot", sample="no"),
* @Attribute("link", type="string", description="task link", sample="http://todo.test/dingoapi/task/1")
* }),
* @Response(404, body={"message":"404not found", "status_code": 404})
* })
*/
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 全程不用写代码,我用AI程序员写了一个飞机大战
· DeepSeek 开源周回顾「GitHub 热点速览」
· 记一次.NET内存居高不下排查解决与启示
· MongoDB 8.0这个新功能碉堡了,比商业数据库还牛
· .NET10 - 预览版1新功能体验(一)