编程学习网 > PHP技术 > laravel > laravel 自动生成api文档
2021
06-22

laravel 自动生成api文档

清华大佬耗费三个月吐血整理的几百G的资源，免费分享！....>>>

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
以上就是“laravel 自动生成api文档”的全部内容，想要获取更多关于laravel相关教程或者资讯欢迎关注编程学习网

扫码二维码 获取免费视频学习资料

Python编程学习

查 看2022高级编程视频教程免费获取