1、简介&安装
Laravel API 文档生成器：
可以基于 Laravel 应用路由自动生成项目 API 文档。
官网：
https://beyondco.de/docs/laravel-apidoc-generator/getting-started/installation
安装：
composer require mpociot/laravel-apidoc-generator
发布配置：
php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config
修改配置：
\config\apidoc.php
‘prefixes‘ => [
‘*‘,
],
修改为
‘prefixes‘ => [
‘api/*‘,
],
这样就不会所有路由都输出到文档中，只有api前缀的才输出。
2、路由
routes\api.php
//--文章
Route::get(‘article‘,‘Api\ArticleController@all‘);
Route::post(‘article‘,‘Api\ArticleController@save‘);
Route::put(‘article/{id}‘,‘Api\ArticleController@update‘);
Route::get(‘article/{id}‘,‘Api\ArticleController@show‘);
Route::delete(‘article/{id}‘,‘Api\ArticleController@destory‘);
//--分类
Route::get(‘category‘,‘Api\CategoryController@all‘);
Route::post(‘category‘,‘Api\CategoryController@save‘);
Route::put(‘category/{id}‘,‘Api\CategoryController@update‘);
Route::get(‘category/{id}‘,‘Api\CategoryController@show‘);
Route::delete(‘category/{id}‘,‘Api\CategoryController@destory‘);
3、控制器
方法里的代码可忽略，主要看注释
文章
<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Model\Article;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
/**
* @group article
* 文章
*/
class ArticleController extends Controller
{
/**
* list
* 文章列表
* @queryParam title string 标题
* @queryParam type int 类型
* @queryParam author string 作者
* @response {
* "error": 0,
* "msg": "ok",
* "data": {
* "id": 2,
* "type": 1,
* "title": "标题",
* "author": "作者",
* "content": "内容",
* "created_at": "1970-01-01 08:00:00",
* "updated_at": "1970-01-01 08:00:00"
* }
* }
*/
public function all(Request $request)
{
$param = $request->all();
$validator = Validator::make($param,[
‘title‘ => ‘string|max:64‘,
‘type‘ => ‘integer|in:1,2‘,
‘author‘ => ‘string|max:64‘,
]);
if ($validator->fails()) {
return $this->responseFormat(1,$validator->errors()->first());
}
$collection = Article::query()
->where(function($query) use($param){
(isset($param[‘title‘]) && !empty($param[‘title‘])) ?
$query->where(‘title‘,‘like‘,‘%‘.$param[‘title‘].‘%‘) : null;
(isset($param[‘type‘]) && !empty($param[‘type‘])) ?
$query->where(‘type‘,$param[‘type‘]) : null;
(isset($param[‘author‘]) && !empty($param[‘author‘])) ?
$query->where(‘author‘,‘like‘,‘%‘.$param[‘author‘].‘%‘) : null;
})
->get();
$collection->transform(function($item){
$item->type_text = Article::$Type[$item->type] ?? ‘‘;
return $item;
});
return $this->responseFormat(0,‘ok‘,$collection);
}
/**
* create
* 新建文章
* @bodyParam title string 标题
* @bodyParam type int 类型
* @bodyParam author string 作者
* @bodyParam content string 内容
* @response {
* "error": 0,
* "msg": "ok",
* "data": []
* }
*/
public function save(Request $request)
{
$param = $request->all();
$validator = Validator::make($param,[
‘title‘ => ‘string|max:64‘,
‘type‘ => ‘integer|in:1,2‘,
‘author‘ => ‘string|max:64‘,
‘content‘ => ‘string|max:255‘,
]);
if ($validator->fails()) {
return $this->responseFormat(1,$validator->errors()->first());
}
$time = time();
Article::create([
‘title‘ => $param[‘title‘],
‘type‘ => $param[‘type‘],
‘author‘ => $param[‘author‘],
‘content‘ => $param[‘content‘],
‘created_at‘ => $time,
‘updated_at‘ => $time,
]);
return $this->responseFormat(0,‘ok‘);
}
/**
* update
* 更新文章
* @urlParam id required ID
* @bodyParam title string 标题
* @bodyParam type int 类型
* @bodyParam author string 作者
* @bodyParam content string 内容
* @response {
* "error": 0,
* "msg": "ok",
* "data": []
* }
*/
public function update(Request $request,$id){
if($id<0){
return $this->responseFormat(1,‘id error‘);
}
$param = $request->all();
$validator = Validator::make($param,[
‘title‘ => ‘string|max:64‘,
‘type‘ => ‘integer|in:1,2‘,
‘author‘ => ‘string|max:64‘,
‘content‘ => ‘string|max:255‘,
]);
if ($validator->fails()) {
return $this->responseFormat(1,$validator->errors()->first());
}
$model = Article::find($id);
if (!$model) {
return $this->responseFormat(1,‘no data‘);
}
$model->title = $param[‘title‘];
$model->type = $param[‘type‘];
$model->author = $param[‘author‘];
$model->content = $param[‘content‘];
$model->save();
return $this->responseFormat(0,‘ok‘);
}
/**
* detail
* 文章详情
* @urlParam id required ID
* @response {
* "error": 0,
* "msg": "ok",
* "data": {
"id": 2,
"type": 1,
"title": "标题",
"author": "作者",
"content": "内容",
"created_at": "1970-01-01 08:00:00",
"updated_at": "1970-01-01 08:00:00"
}
* }
*/
public function show($id){
if($id<0){
return $this->responseFormat(1,‘id error‘);
}
$model = Article::find($id);
if (!$model) {
return $this->responseFormat(1,‘no data‘);
}
return $this->responseFormat(0,‘ok‘,$model);
}
/**
* delete
* 删除文章
* @urlParam id required ID
* @response {
* "error": 0,
* "msg": "ok",
* "data": []
* }
*/
public function destory($id)
{
if($id<0){
return $this->responseFormat(1,‘id error‘);
}
$model = Article::find($id);
if (!$model) {
return $this->responseFormat(1,‘no data‘);
}
$model->deleted_at = time();
$model->save();
return $this->responseFormat(0,‘ok‘);
}
}
分类
<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
/**
* @group 分类
* 分类管理
*/
class CategoryController extends Controller
{
/**
* 分类列表
* @queryParam name string 分类名称
* @response {
* "error": 0,
* "msg": "ok",
* "data": {
* "id": 2,
* "name": "分类名称",
* "sort": 1,
* "created_at": "1970-01-01 08:00:00",
* "updated_at": "1970-01-01 08:00:00"
* }
* }
*/
public function all()
{
return __METHOD__;
}
/**
* 新建分类
* @bodyParam name string 分类名称
* @bodyParam sort int 排序
* @response {
* "error": 0,
* "msg": "ok",
* "data": []
* }
*/
public function save()
{
return __METHOD__;
}
/**
* 更新分类
* @urlParam id required ID
* @bodyParam name string 分类名称
* @bodyParam sort int 排序
* @response {
* "error": 0,
* "msg": "ok",
* "data": []
* }
*/
public function update()
{
return __METHOD__;
}
/**
* 分类详情
* @urlParam id required ID
* @response {
* "error": 0,
* "msg": "ok",
* "data": {
* "id": 2,
* "name": "分类名称",
* "sort": 1,
* "created_at": "1970-01-01 08:00:00",
* "updated_at": "1970-01-01 08:00:00"
* }
* }
*/
public function show()
{
return __METHOD__;
}
/**
* 删除分类
* @urlParam id required ID
* @response {
* "error": 0,
* "msg": "ok",
* "data": []
* }
*/
public function destory()
{
return __METHOD__;
}
}
4、生成接口文档
php artisan apidoc:generate
5、访问
xx.com/docs
6、有个坑
文章的导航点击正常，分类的导航不能点击。
原因是中文的关系，将类@group和方法的第一行注释，改为英文即可。
7、修改logo
找张图片替换 \resources\docs\source\assets\images\logo.png，（ 尺寸：230 x 52 ）
执行：
php artisan apidoc:rebuild
php artisan apidoc:generate