laravel 自动生成api文档

1、简介&安装

Laravel API 文档生成器：

可以基于 Laravel 应用路由自动生成项目 API 文档。

官网：

https://beyondco.de/docs/laravel-apidoc-generator/getting-started/installation

安装：

copycomposer require mpociot/laravel-apidoc-generator

发布配置：

copyphp artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

修改配置：

\config\apidoc.php

copy'prefixes' => [
	'*',
],

修改为

copy'prefixes' => [
	'api/*',
],

这样就不会所有路由都输出到文档中，只有api前缀的才输出。

2、路由

routes\api.php

copy//--文章
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、控制器

方法里的代码可忽略，主要看注释

文章

copy<?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');
	}
}

分类

copy<?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__;
	}
}