Laravel 中使用 DingoAPI
- 2019 年 12 月 17 日
- 筆記
Laravel 中使用 DingoAPI
安装laravel 这里以5.5版本为例
composer create-project laravel/laravel laravel-api --prefer-dist "5.5.*"
1. 安装 DingoAPI
composer require dingo/api:2.0.0-alpha2
发现报错
Problem 1 - Conclusion: remove laravel/framework v5.5.40 - Conclusion: don't install laravel/framework v5.5.40 - dingo/blueprint 0.2.2 requires illuminate/filesystem 5.1.* || 5.2.* || 5.3.* || 5.4.* -> satisfiable by illuminate/filesystem[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.28, v5.1.30, v5.1.31, v5.1.41, v5.1.6, v5.1.8, v5.2.0, v5.2.19, v5.2.21, v5.2.24, v5.2.25, v5.2.26, v5.2.27, v5.2.28, v5.2.31, v5.2.32, v5.2.37, v5.2.43, v5.2.45, v5.2.6, v5.2.7, v5.3.0, v5.3.16, v5.3.23, v5.3.4, v5.4.0, v5.4.13, v5.4.17, v5.4.19, v5.4.27, v5.4.36, v5.4.9]. - dingo/blueprint v0.2.0 requires illuminate/filesystem 5.1.* || 5.2.* || 5.3.* -> satisfiable by illuminate/filesystem[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.28, v5.1.30, v5.1.31, v5.1.41, v5.1.6, v5.1.8, v5.2.0, v5.2.19, v5.2.21, v5.2.24, v5.2.25, v5.2.26, v5.2.27, v5.2.28, v5.2.31, v5.2.32, v5.2.37, v5.2.43, v5.2.45, v5.2.6, v5.2.7, v5.3.0, v5.3.16, v5.3.23, v5.3.4]. - dingo/blueprint v0.2.1 requires illuminate/filesystem 5.1.* || 5.2.* || 5.3.* -> satisfiable by illuminate/filesystem[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.28, v5.1.30, v5.1.31, v5.1.41, v5.1.6, v5.1.8, v5.2.0, v5.2.19, v5.2.21, v5.2.24, v5.2.25, v5.2.26, v5.2.27, v5.2.28, v5.2.31, v5.2.32, v5.2.37, v5.2.43, v5.2.45, v5.2.6, v5.2.7, v5.3.0, v5.3.16, v5.3.23, v5.3.4]. - don't install illuminate/filesystem v5.1.1|don't install laravel/framework v5.5.40 ...
因为这个包尚处在开发阶段，暂时没有稳定版，因此 我们需要手动添加。
打开 composer.json 手动添加 手动添加 "dingo/api": "2.0.0-alpha2"
"require": { "php": ">=7.0.0", "fideloper/proxy": "~3.3", "laravel/framework": "5.5.*", "laravel/tinker": "~1.0", "dingo/api": "2.0.0-alpha2" },
执行composer update
composer update
稍等片刻，哇哦，顺利安装……
2. 配置
将 dingo 的配置文件发布出来
php artisan vendor:publish
Which provider or tag's files would you like to publish?: [0] Publish files from all providers and tags listed below [1] Provider: DingoApiProviderLaravelServiceProvider [2] Provider: FideloperProxyTrustedProxyServiceProvider [3] Provider: IlluminateMailMailServiceProvider [4] Provider: IlluminateNotificationsNotificationServiceProvider [5] Provider: IlluminatePaginationPaginationServiceProvider [6] Provider: LaravelTinkerTinkerServiceProvider [7] Tag: laravel-mail [8] Tag: laravel-notifications [9] Tag: laravel-pagination
按照命令行交互，我们输入 1 即可。接着就会在 config 目录下生成 api.php,可以打开大体浏览下各项配置，里面的每一项都可以用 env 文件来配置。
我们暂时只关心如下配置：
- API_STANDARDS_TREE
- API_SUBTYPE
- API_VERSION
- API_PREFIX
- API_DOMAIN
- API_NAME
- API_STRICT
- API_DEBUG
接下来 针对以上配置一一作出解释：
-
API_STANDARDS_TREE： 有三个可选值：x: 本地开发的或私有环境的prs: 主要用于非商业销售的项目,未对外发布vnd：对外公开，所有用户可以访问
-
API_SUBTYPE：项目的简称，或者项目名称 -
API_VERSION： 版本号 -
API_PREFIX和API_DOMAIN： 前缀和子域名， 前缀或子域名是必须的，并且同时只有一个 -
API_NAME: API的名字只有在使用API Blueprint命令生成文档的时候才用到，这个名字作为默认名字以免生成文档时需要手动指定名字。 -
API_STRICT: 严格解析，值为 true 或 false，默认为 false ，开启严格解析，意味着你不可以使用浏览器来进行访问。 -
API_DEBUGdeuug 模式，方便查看错误信息
其他还有一些，分别为响应格式、错误格式、认证等等，就不一一介绍了。
我们打开 .env 文件，配置刚才所说的参数
API_STANDARDS_TREE=x API_SUBTYPE=laravel-api API_PREFIX=api API_VERSION=v1 API_DEBUG=true
3. 编写测试接口
我们知道 laravel 路由文件 有专门的api 路由文件。打开该文件
<?php use IlluminateHttpRequest; /* |-------------------------------------------------------------------------- | API Routes |-------------------------------------------------------------------------- | | Here is where you can register API routes for your application. These | routes are loaded by the RouteServiceProvider within a group which | is assigned the "api" middleware group. Enjoy building your API! | */ Route::middleware('auth:api')->get('/user', function (Request $request) { return $request->user(); });
由于我们使用 DingoApi ，因此我们同样使用 DingoApi 的路由。将内容全部替换 如下内容：
<?php use IlluminateHttpRequest; $api = app('DingoApiRoutingRouter'); $api->version('v1', function($api) { $api->get('test', function() { return response('hello word'); }); });
使用接口调试工具 来进行测试 推荐使用 POSTMAN 调试工具，
- 网址中输入地址
http://laravel-api.test/api/test,不出意外 应该会输出 hello world 字样 - 另外一种很常见的访问方式是通过 Accept 添加头信息 Headers
Accept: application/x.laravel-api.v1+json
似乎很难看出效果，我们新增一条路由试试。
. . . $api->version('v2', function($api) { $api->get('test', function() { return response('hello laravel'); }); });
接着改变 Accept
Accept: application/x.laravel-api.v2+json
ok,以上我们仅仅是测试我们的接口是不是可以正常用心，实际项目中，我们不可能所有的代码都放在路由文件中。接下来，我们新建控制器来替换路由的示例代码。
首先，我们新建一个基类控制器，让我们的所有其他控制器，默认继承我们新建的控制器。
php artisan make:controller Api/v1/Controller php artisan make:controller Api/v2/Controller
我们引入 DingoApi的 Helpers 来处理有关接口的响应
可以看出，我们在 appHttpControllers 新建了一个文件夹 Api ，同时在此目录下又新建了 v1和 v2目录
新建
Api目录，我们是为了和其他web控制器区分，我们将所有有关接口的控制器都放到Api目录下.增加v1和v2我们是为了后续的版本管理
打开这两个控制器， 替换如下代码：
<?php namespace AppHttpControllersApiv1; use DingoApiRoutingHelpers; use IlluminateHttpRequest; use AppHttpControllersController as BaseController; class Controller extends BaseController { use Helpers; }
同理：v2 下也是这样修改 （注意命名空间，不要全部复制，记得修改哦）。
新增控制器，比如我们添加一个 Users 控制器
php artisan make:controller Api/v1/UsersController php artisan make:controller Api/v2/UsersController
打开新建的 UsersController，替换成如下代码：
<?php namespace AppHttpControllersApiv1; use IlluminateHttpRequest; class UsersController extends Controller { public function store() { return $this->response->array(['errmsg' => 'this is v1']); } }
v2 下我们稍微改变下返回数据，以便直观看出
<?php namespace AppHttpControllersApiv2; use IlluminateHttpRequest; class UsersController extends Controller { public function store() { return $this->response->array(['errmsg' => 'this is v2']); } }
控制器就算完成了，我们添加两条路由。
. . . $api->version('v1', [ 'namespace' => 'AppHttpControllersApiv1' ], function($api) { $api->post('users', 'UsersController@store') ->name('api.v1.users.store'); }); $api->version('v2', [ 'namespace' => 'AppHttpControllersApiv2' ], function($api) { $api->post('users', 'UsersController@store') ->name('api.v2.users.store'); });
增加了一个
namespace参数，目的是所有路由都会指向 该namespace。
访问方法和上面一样。
ok,以上就是 laravel 中初步安装 DingoApi ，并且配置的基础教程，更多使用请阅读 官方文档
