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