PHPackages                             rockyfc/laravel-smart-apidoc - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. rockyfc/laravel-smart-apidoc

ActiveLibrary[API Development](/categories/api)

rockyfc/laravel-smart-apidoc
============================

laravel api项目，根据逻辑生成接口文档

v2.0.1(6mo ago)0133MITPHPPHP ^7.2 || ^8.0

Since May 10Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/rockyfc/laravel-smart-apidoc)[ Packagist](https://packagist.org/packages/rockyfc/laravel-smart-apidoc)[ RSS](/packages/rockyfc-laravel-smart-apidoc/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (2)Versions (17)Used By (0)

laravel-smart-apidoc
====================

[](#laravel-smart-apidoc)

根据程序逻辑自动生成laravel文档。

\###简介

1. 实时文档。文档根据动态逻辑生成，逻辑修改，文档会随之自动更新。
2. 有效解决文档和程序的脱钩问题。文档和实际程序的脱钩问题是常规手动维护文档产生的最大的问题。
3. 执行路由的双向检查。

- 可以检查程序中的空路由，并抛出异常。
- 可以检查没有指定路由的空接口（action），并抛出异常。

4. 开放文档程序接口给调用者。

- 文档程序向外部公开了获取所有接口文档的接口。便于自定义文档系统。

\###安装方法

命令行执行：

```
composer require rockyfc/laravel-smart-apidoc
```

在命令行执行如下命令：

```
php artisan smart:install-doc
```

完成安装，访问 `http://xxx.xx/smart-doc` 查看文档首页。

\###使用方法

Laravel框架的表单层RequestForm和资源层Resource为该文档程序的实现的基石，也就是说，程序中只要使用了表单和资源两大组件，即可实现强大的文档功能。但 不可否认，编写文档程序过程中，始终坚持文档绝不影响业务实现、文档决不对业务造成代码污染、文档绝不影响laravel内置的优秀特性为大前提。可以让使用者在业务 开发中无需额外关心文档如何生成。

文档程序在开发中，对于几种典型的增删改查业务场景做了支持。

**列表查询接口**

列表查询接口往往涉及到返回值存在多条资源，且伴有分页、排序、等功能，如何让文档智能识别是首要问题。

**识别当前接口为数据列表：**

接口的注释内容中的`@return`标签返回的值类型，标注为`Illuminate\Http\Resources\Json\ResourceCollection`或者它的子类，文档程序便可以识别 此接口的返回值是一个数据列表。当然，强大的IDE也实现了自动生成注释的功能，无需手动输入。示例代码如下：

```
    /**
     * 接口标题
     * ...
     *
     * @return AnonymousResourceCollection
     * ...
     */
    public function index(FormRequest $request)
    {
        //code...
    }
```

**识别当前列表接口是否带有分页：**

在注释中添加一个`@see`标签，并且标签的内容为`Illuminate\Pagination\AbstractPaginator`或者它的子类，便可被识别为列表接口带有分页功能。

```
    /**
     * 接口标题
     * ...
     * @see LengthAwarePaginator
     * @return AnonymousResourceCollection
     * ...
     */
    public function index(FormRequest $request)
    {
        //code...
    }
```

**识别排序功能：**

排序功能需要显示的指明可以按照哪些字段排序，并且允许这些字段在客户端来输入，所以，识别排序需要在表单层中实现一个`sort()`函数来标记排序。

```
    /**
     * 需要排序的字段
     * @return string[]
     */
    public function sorts()
    {
        return ['id', 'updated_at'];
    }
```

**识别当前接口为创建，编辑，删除等接口：**

除了带有分页的接口相对麻烦一点，其他接口都变的很简单，只需正确使用http动词get，post，put，delete即可，action的注释用IDE自动生成就好。

以下以分类接口为例子，为大家展示一个增删改查接口的使用范例：

```