laravel 自動生成api文件
阿新 • • 發佈：2020-06-12
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\[email protected]‘);
Route::post(‘article‘,‘Api\[email protected]‘);
Route::put(‘article/{id}‘,‘Api\[email protected]‘);
Route::get(‘article/{id}‘,‘Api\ 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‘,‘%‘.$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,* "data": []
* }
*/
public function save(Request $request)
{
$param = $request->all();
$validator = Validator::make($param,‘content‘ => ‘string|max:255‘,$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,* "data": []
* }
*/
public function update(Request $request,$id){
if($id<0){
return $this->responseFormat(1,‘id error‘);
}
$param = $request->all();
$validator = Validator::make($param,$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,* "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,$model);
}
/**
* delete
* 刪除文章
* @urlParam id required ID
* @response {
* "error": 0,* "data": []
* }
*/
public function destory($id)
{
if($id<0){
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,* "name": "分類名稱",* "sort": 1,* "updated_at": "1970-01-01 08:00:00"
* }
* }
*/
public function all()
{
return __METHOD__;
}
/**
* 新建分類
* @bodyParam name string 分類名稱
* @bodyParam sort int 排序
* @response {
* "error": 0,* "data": []
* }
*/
public function save()
{
return __METHOD__;
}
/**
* 更新分類
* @urlParam id required ID
* @bodyParam name string 分類名稱
* @bodyParam sort int 排序
* @response {
* "error": 0,* "data": []
* }
*/
public function update()
{
return __METHOD__;
}
/**
* 分類詳情
* @urlParam id required ID
* @response {
* "error": 0,* "updated_at": "1970-01-01 08:00:00"
* }
* }
*/
public function show()
{
return __METHOD__;
}
/**
* 刪除分類
* @urlParam id required ID
* @response {
* "error": 0,* "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