2.3. 创建端点

一个端点是一个路由的另一种说法。当讨论 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 命令相同。