在Laravel5.2中使用dingo+JWT+Swagger

项目github地址laravel-dingo

结合dingo api、JWT、swagger等众多目前流行的restful api工具，致力于将laravel5.2打造成更加适合API开发者开发API的工作环境，
并将路由分割到各个控制器中，避免众多路由混杂到一个routes.php文件中，便于日常维护!

使用

Note:在使用该框架之前，先要搭建好web服务器环境，本框架在nginx+php+mysql环境下能测试通过！

下载

git clone https://github.com/turtleliangzi/laravel-dingo.git

修改目录权限

chmod -R 777 storage

chmod -R bootstrap/cache

测试数据准备

本框架使用的数据库、用户名、密码分别为ucenter、root、ucenter，用户可以在.env文件中修改为自己的数据库、用户名和密码。

DB_DATABASE=ucenterDB_USERNAME=rootDB_PASSWORD=ucenter

生成测试表

php artisan migrate

生成users表测试数据

php artisan tinker

进入交互界面

>>> namespace App=> null>>> factory(User::class, 60)->create()

lessons表测试数据可以按照同样方法生成。

Dingo Api

Dingo Api是一个强大的laravel API编写工具, 使用它，可以更加规范和方便地编写API，节约大量开发时间。Dingo Api

配置

本框架已经安装并配置好了Dingo Api，在使用过程中，你可以修改.env文件中的以下配置

API_STANDARDS_TREE=vnd

API_PREFIX=api

API_VERSION=v1

API_DEBUG=true

具体配置详情，请参考dingo api configuration

使用

在app/Http/routes.php文件中注册以下路由

/* * Include  Routes */$root_dir = '/var/www/dingo/app/Api/';$api = app('Dingo\Api\Routing\Router');// V1require_once $root_dir.'V1/routes.php';

在app目录下新建Api/V1文件夹，在V1文件夹下新建routes.php文件，写入以下内容

$api->version('v1', function ($api) {    $api->group(['namespace' => 'App\Api\V1\Controllers'], function($api) {        /*         * include controller routes         */        $dir = '/var/www/dingo/app/Api/V1/Controllers/';        // User Controller Routes        require_once $dir.'User/routes.php';    }); });

在V1文件夹下新建Controllers文件夹，在Controllers文件夹下新建BaseController.php文件

<?phpnamespace  App\Api\V1\Controllers;use App\Http\Controllers\Controller;use Dingo\Api\Routing\Helpers;class BaseController extends Controller {    use Helpers;}

在Controllers文件夹下新建User文件夹，在User文件夹下新建routes.php文件

/* * User Controller Routes * */$api->get('/users/all', 'User\UserController@show');

至此，路由注册完毕，过程中，将路由分割到了各个控制器中，目地是为了更方便维护。

在User文件夹下新建UserController.php文件，继承BaseController

<?phpnamespace App\Api\V1\Controllers\User;use App\Api\V1\Controllers\BaseController;use App\User;class UserController extends BaseController {    public function show() {        $users =  User::all();        return $users;    }}

在浏览器打开www.example.com/api/users/all，如果能够得到想要的，则路由注册成功。

JWT

JWT（JSON WEB TOKEN）一种API验证方式，详情请见JWT

Note：在本框架中已经安装并配置好了JWT，可以直接使用。

使用

在app/Api/V1/Controllers下新建Auth文件夹，在Auth文件夹下面新建AuthController.php文件

<?phpnamespace App\Api\V1\Controllers\Auth;use App\Api\V1\Controllers\BaseController;use Illuminate\Http\Request;use JWTAuth;use Tymon\JWTAuth\Exceptions\JWTException;use App\User;class AuthController extends BaseController {    public function authenticate(Request $request) {        // grab credentials from the request        $credentials = $request->only('email', 'password');        try {            // attempt to verify the credentials and create a token for the user            if (! $token = JWTAuth::attempt($credentials)) {                return response()->json(['error' => 'invalid_credentials'], 401);            }        } catch (JWTException $e) {            // something went wrong whilst attempting to encode the token            return response()->json(['error' => 'could_not_create_token'], 500);        }        // all good so return the token        return response()->json(compact('token'));    }}

注册路由，在Auth文件夹下新建routes.php文件

/* * Auth Controller Routes * */$api->post('/auth/login', 'Auth\AuthController@authenticate');

修改app/Api/V1/routes.php文件，引入Auth/routes.php文件

$api->version('v1', function ($api) {    $api->group(['namespace' => 'App\Api\V1\Controllers'], function($api) {        /*         * include controller routes         */        $dir = '/var/www/dingo/app/Api/V1/Controllers/';        // Auth Controller Rotues        require_once $dir.'Auth/routes.php';        // User Controller Routes        require_once $dir.'User/routes.php';    }); });

访问链接www.example.com/api/auth/login，登陆成功可以返回一串token值。可以结合register方法，先注册一个测试用户。

在AuthController.php中加入

public function register(Request $request) {        $newUser = [             'name' => $request->get('name'),            'email' => $request->get('email'),            'password' => bcrypt($request->get('password')),        ];        $user = User::create($newUser);        $token = JWTAuth::fromUser($user);        return response()->json(compact('token'));    }

修改该目录下的routes.php，注册/auth/register路由

$api->post('/auth/login', 'Auth\AuthController@authenticate');$api->post('/auth/register', 'Auth\AuthController@register');

可以在一个路由或路由组中使用jwt.auth中间件，通过token来验证获取资源的权限。

$api->group(['middleware' => 'jwt.auth'], function($api) {            $dir = '/var/www/dingo/app/Api/V1/Controllers/';            // User Controller Routes            require_once $dir.'User/routes.php';});

当访问www.example.com/api/user/all时，需要在加上Header Authorization: Bearer {yourtokenhere}。

Swagger

Swagger是一个非常强大的API文档工具， 在Laravel中使用Swagger可以自动生成Api文档，详情请见swaggervel

Note：本框架中已经安装并配置好了swagger，可以直接使用。

例如：

use Swagger\Annotations as SWG;/** * @SWG\Swagger( *   @SWG\Info( *     title="Dingo Api", *     version="1.0.0" *   ), *   @SWG\Tag(name="Auth", description="验证模块"), *   @SWG\Tag(name="Users", description="用户模块"), *   @SWG\Tag(name="Lessons", description="教程模块"), *   schemes={"http"}, *   host="ucenter.turtletl.com:81", *   basePath="/api" * ) */class UserController extends BaseController {    /**      * @SWG\Get(     *   path="/users/all",     *   summary="显示所有用户",     *   tags={"Users"},     *   @SWG\Parameter(name="Authorization", in="header", required=true, description="用户凭证", type="string"),     *   @SWG\Response(     *     response=200,     *     description="all users"     *   ),     *   @SWG\Response(     *     response="default",     *     description="an ""unexpected"" error"     *   )     * )     */     public function show() {        $users =  User::all();        $users = User::paginate(25);        return $this->response->paginator($users, new UserTransformer)->setStatusCode(200);        //return $this->response->collection($users, new UserTransformer);    }    /**     * @SWG\Get(     *   path="/users/one",     *   summary="获取当前用户",     *   tags={"Users"},     *   @SWG\Parameter(name="Authorization", in="header", required=true, description="用户凭证", type="string"),     *   @SWG\Response(     *     response=200,     *     description="one user"     *   ),     *   @SWG\Response(     *     response="default",     *     description="an ""unexpected"" error"     *   )     * )     */     public function getAuthenticatedUser()    {        try {            if (! $user = JWTAuth::parseToken()->authenticate()) {                return response()->json(['user_not_found'], 404);            }        } catch (TokenExpiredException $e) {            return response()->json(['token_expired'], $e->getStatusCode());        } catch (TokenInvalidException $e) {            return response()->json(['token_invalid'], $e->getStatusCode());        } catch (JWTException $e) {            return response()->json(['token_absent'], $e->getStatusCode());        }        // the token is valid and we have found the user via the sub claim        return response()->json(compact('user'));        //return $this->response->item(compact('user'), new UserTransformer);    }

Swagger-php 2.0 较Swagger-php 1.0版本有一定的改动，详情请见swagger-php2.0

访问www.example.com/api-docs查看API文档

访问www.example.com/docs查看JSON文档

详情请参考本框架测试环境下的API文档laravel-dingo