在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=ucenter
DB_USERNAME=root
DB_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');

// V1
require_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文件

<?php

namespace  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

<?php

namespace 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文件

<?php

namespace 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