创建端点
一个端点是一个路由的另一种说法。当讨论 API 的时候,很多人把访问的路由称作为一个端点。
版本组
为了避免与你主要的项目路由冲突,dingo/api 将会使用其专属的路由实例。要创建端点,我们首先需要获得一个 API 路由的实例:
$api = app('Dingo\Api\Routing\Router');
现在我们必须定义一个版本分组。这种定义方式有利于后续为相同端点新增多版本支持。
$api->version('v1', function ($api) {
});
如果你想一个分组返回多个版本,只需要传递一个版本数组。
$api->version(['v1', 'v2'], function ($api) {
});
通过在第二个参数上传递一个属性数组,你也可以将此组视为特定框架的标准组。
$api->version('v1', ['middleware' => 'foo'], function ($api) {
});
你还可以嵌套常规组以进一步定制某些端点。
$api->version('v1', function ($api) {
$api->group(['middleware' => 'foo'], function ($api) {
// Endpoints registered here will have the "foo" middleware applied.
});
});
创建端点
一旦你有了一个版本分组,你就可以在分组闭包的参数中,通过 $api
创建端点。
$api->version('v1', function ($api) {
$api->get('users/{id}', 'App\Api\Controllers\UserController@show');
});
因为端点被每个版本分组了,你可以为相同 URL 上的同一个端点创建不同响应。
$api->version('v1', function ($api) {
$api->get('users/{id}', 'App\Api\V1\Controllers\UserController@show');
});
$api->version('v2', function ($api) {
$api->get('users/{id}', 'App\Api\V2\Controllers\UserController@show');
});
你也可以使用各自的方法注册资源和控制器。
提醒,你需要为控制器添加说明完整的命名空间,比如,
App\Http\Controllers
.
命名路由和生成 URLs
命名你的路由可以使你方便的生成他们的 URL。你可以跟 Laravel 一样的方法命名你的路由。
$api->get('users/{id}', ['as' => 'users.index', 'uses' => 'Api\V1\UserController@show']);
现在你可以为命名的路由生成 URL 了。
app('Dingo\Api\Routing\UrlGenerator')->version('v1')->route('users.index');
你需要提供一个版本,这样才能基于这个版本的路由生成正确的 URL。并且允许你在不同版本中使用相同的名字。
在命令行中查看路由
如果你正在使用 Laravel 5.1 你可以使用 Artisan 命令看到你注册的路由。
$ php artisan api:routes
这个命令和 Laravel 自带的 route:list
命令相同。