laravel开发RESTful API文档的一些心得

最近用laravel 写了一段时间的 API，总结一下自己的心得吧。

Start
API开发我们可以看到，有些网站用token验证身份，有些用OAuth2.0，当时我也纠结，然后看到一个不错的说法。大方面，会涉及到给别人用的使用OAuth，自己使用的用token就足够了
设计最初，最好在路由加个版本号，方便以后扩展

Route::prefix('v1')->group(function () {
    // more
});

如果前端想跨域，请使用这个很方便的包barryvdh/laravel-cors
一个简单的接口示例
api实例输出

验证
API 开发总会离不开验证，这里推荐使用jwt-auth，1.0 快要来了，新版本的文档也很清晰
刚用jwt-auth时有疑问，Laravel自带的token验证使用的是数据库api_token字段验证，而不见jwt-auth需要这个
然后想自己看源码，结果QAQ
最后去问了官方 >_<
原来用户的信息已经存储在token中加密
一开始有疑问，这样保存，不会被解密吗(真为自己智商担忧 !_!)
后来才想起，jwt一开始就运行php artisan jwt:secret生成了秘钥
你不泄露就保证安全了~~~
路由
当然使用官方api的路由Route::apiResource(),一条更比五条强
路由的名字当然是RESTful的方式
保持动词，复数形式，见名知义
有些长的路由，应该用什么分隔呢？
laravel用的是中划线(-)，因为谷歌收录时，按中划线划分关键字，国内的是按下划线(_)收录，具体看自己了，我是喜欢下划线 >_<
更多看这里：路由命名规范
表单验证
可以使用控制器自带的表单验证，更推荐使用表单类,能分离都分离出去，控制器不要处理太多事情。

能分离的代码都不要吝啬~~~

数据转换
Laravel自带的API Resource
用起来真的很方便，不过发现一个问题，--collection的格式总是转不过来，后来直接放弃了
单个的使用Resources
集合的使用Resources::collection()发现，特别好用 >_<
不得不说，多对多关联时，Laravel处理得太好了条件关联
数据转换

在上面这个例子中，如果关联没有被加载，则 posts 键将会在资源响应被发送给客户端之前被删除。
在有不确定是否输出关联数据时，这是一个很有用的功能！！！
响应输出
当时在 laravel-china 看到的这个帖子，然后觉得这个方式不错，所以自己也这样子，使用基类的方法统一响应输出。

异常
异常算是一大手笔了，处理好异常，可以让你的代码优雅很多。
\App\Exceptions\Handler::render方法可以捕获到很多有用的异常，例如，我的代码是这样写的：
异常捕获

UnauthorizedHttpException这个是捕获jwt异常
ValidationException这个是表单异常，捕获之后，表单错误消息可以很好的格式化，
ModelNotFoundException这个是模型找不到的异常，捕获之后，可以直接在控制器直接这样

// 未捕获之前的写法
public function show($id)
{
    $user = User::find($id);
    if (! $user) {

    }

    // do something
}

// 现在
public function show($id)
{
    $user = User::findOrFail($id);
}
// 甚至这样
public function show(User $user)
{
    // do something
}

下面这两个异常可以不捕获，只是方便开发中查看错误消息
NotFoundHttpException404路由找不到的异常，没什么好说的了
MethodNotAllowedHttpException这个是方法不对应，比如你是get路由，却post请求
文档
差点忘了这个，文档非常非常重要
我是不怎么喜欢在注释写文档的
使用swagger-ui+swagger-edit
下载swagger-ui
只需要dist目录的东西（其他可以删除了）
下载swagger-editor
只要dist目录的东西和根目录的index.html
我还把swagger-editor的index.html改成了edit.html，然后把这两个东西整合到同一个目录（记得修改css,js的位置）
新建两个文件api.json,api.yaml 大概就和图中差不多
要修改图中箭头所示成为api.json的位置
api