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