1、簡介&安裝

laravel API 文檔生成器：

可以基于 Laravel 應用路由自動生成項目 API 文檔。

安裝：

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自動生成接口文檔”的詳細內容，想要獲取更多laravel教程歡迎關注編程學習網