README

介绍

PHP框架API文档生成工具, 无需生成静态文档. 动态生成. 目前完成了基于Laravel的实现.

软件架构

软件架构说明

安装教程

Composer安装

我本人的开发环境是PHP7.3, 目前还没有做向下兼容的测试

composer require spool/apiinfo

运行这个命令添加资源和配置

php artisan vendor:publish --tag=apiinfo

打开 http://localhost/apiinfo/ 即可看到演示页面。

使用说明

配置说明

framework定义使用的框架, 目前只支持Laravel和DingoApi, 以后会逐渐增加对其他框架（如：Lumen、ThinkPHP等）的支持。 default是要扫描的路由前缀分组, 如针对不同的前端有不同的api文档,可以定义多个；如果是Dingo则无所谓。

prefix定义该分组要扫描的路径前缀, 如果有多个前缀可以定义多个, 都会包含在一个文档页面里。

配置代码

config/apiinfo.php

//ApiInfo配置文件
return [
    'framework' => 'laravel',
    'default' => [
        /**
         * 要扫描的路由前缀
         */
        'prefix' => ['exampleApiinfo'],
    ],
    'default1' => [
        /**
         * 要扫描的路由前缀
         */
        'prefix' => ['api'],
    ],
];

页面模板

路径在 /resources/views/vendor/apiinfo 可以修改. 另希望能有前端贡献好看的页面模板

文档生成

样例控制器在 vendor/spool/apiinfo/src/Controllers/ExampleController.php 里面, 可以参照这个控制器来编写文档.

为了便于文档生成, 提供了Spool\ApiInfo\Requests\BaseRequest Spool\ApiInfo\Requests\PageRequest两个请求类, 作为控制器的参数.

对比Swagger和ApiDoc

每次修改后不需要生成静态页面, 实时修改, 实时更新, 不会因为忘记修改导致文档过时.
不需要添加大量的注释来辅助文档生成, 只需填写几个常用的注释即可.
完全基于PHP实现, 源代码可控.

注释说明:

/**
 * 演示控制器 -- 分组名称
 */
class ExampleController extends Controller
{
    /**
     * 演示控制器get文档 -- 接口名称
     *
     * 演示控制器get方法描述 -- 接口介绍
     * 写点什么
     * 接口简介
     *
     * @param PageRequest $request 请求 -- 参数类
     *
     * @return  array {"code":1,"msg":"err"} -- 接口返回值示例json格式
     * @version 1.0.0 -- 接口版本号
     * @example {"code":0,"msg":"success"} -- 接口返回值示例json格式
     * @example {"code":1,"msg":"err"} 失败 -- 接口返回值示例json格式
     */
    public function getM(PageRequest $request): array
    {
        return ['code' => 0, 'mesg' => 'ok', 'url' => $request->getBaseUrl()];
    }
}

类注释第一行是分组名称, 没有注释时将取类名作为分组名称.
方法注释第一行是接口名称, 没有注释时将取方法名作为接口名称.
第一行之外没有@开头的注释将作为接口介绍
参数列表优先取方法定义的参数getM(PageRequest $request), 支持任意类型, 不过对自带的BaseRequest衍生的类支持最好
@return [type] 后面的json字符串可以解析为返回值示例.
@return 没有定义返回值时会提示{"Document location":"@return mixed doc","format":"json"}
@version 定义接口的版本号
@example 定义成功|失败及其他需要标注的返回值示例
其他参数如GET|POST|PUT|ANY, 以及请求路径都是从路由定义里面获取的, 无需单独定义
生成页面上方的输入框可以自定义要访问的域名, 如果不是本地域名需要解决跨域问题
http://localhost/apiinfo?modelName=default 可以指定要访问配置文件, 用于多前端接口文档的区分

参与贡献

Fork 本仓库
新建 Feat_xxx 分支
提交代码
新建 Pull Request

特技

使用 Readme_XXX.md 来支持不同的语言，例如 Readme_en.md, Readme_zh.md
Gitee 官方博客 blog.gitee.com
你可以 https://gitee.com/explore 这个地址来了解 Gitee 上的优秀开源项目
GVP 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
Gitee 官方提供的使用手册 https://gitee.com/help
Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 https://gitee.com/gitee-stars/

更新说明

v0.1.2

修复了在使用dingoapi过程中出现的部分Bug, 导致文档无法显示的问题.

spool / apiinfo

Maintainers

Details

README

介绍

软件架构

安装教程

使用说明

注释说明:

参与贡献

特技

更新说明

v0.1.2