root
164 lines
7.1 KiB
PHP
164 lines
7.1 KiB
PHP
<?php
|
|
|
|
use think\migration\Migrator;
|
|
|
|
class PluginApiDoc extends Migrator
|
|
{
|
|
public function change()
|
|
{
|
|
$table = $this->table('plugin_apidoc', [
|
|
'engine' => 'InnoDB',
|
|
'comment' => 'Api文档',
|
|
'collation' => 'utf8mb4_general_ci',
|
|
]);
|
|
|
|
//删除表
|
|
if ($table->exists()) {
|
|
$table->drop();
|
|
}
|
|
|
|
$table
|
|
->addColumn('title', 'string', ['limit' => 255, 'default' => '', 'comment' => '标题'])
|
|
->addColumn('des', 'text', ['comment' => '描述'])
|
|
->addColumn('create_time', 'datetime', ['null' => 1, 'comment' => '创建时间'])
|
|
->addColumn('update_time', 'datetime', ['null' => 1, 'comment' => '更新时间'])
|
|
->addColumn('delete_time', 'datetime', ['null' => 1, 'comment' => '删除时间'])
|
|
;
|
|
|
|
$data = [
|
|
[
|
|
'title' => '文档更新',
|
|
'des' => '本文档分为两个部分，`全局说明文档`和`其他文档`。
|
|
|
|
# 全局说明文档
|
|
全局说明下的文档在后台生成Api文档菜单中进行添加，添加完成后点击生成Api文档按钮即可在本文档中看见
|
|
|
|
# 其他文档
|
|
其他文档使用PHP程序，通过PHP的类反射机制，获取到`app/controller/api/`目录下所有文件的注解来进行生成。
|
|
|
|
注解规则请查阅`laytp.com`官网手册或者框架`app/controller/api/Demo.php`文件。
|
|
|
|
如果后端程序员更新了`api`接口程序，并且使用了相应的注解规则，在后台点击`生成Api文档`按钮即可在本文档看到最新的Api文档
|
|
|
|
# 注意点
|
|
由于文档使用的是静态html展示，而浏览器对html页面是有缓存的。所以如果文档进行了更新。可能需要强制刷新页面才能看到最新的文档。',
|
|
'create_time' => date('Y-m-d H:i:s'),
|
|
'update_time' => date('Y-m-d H:i:s'),
|
|
],
|
|
[
|
|
'title' => '在线测试功能使用',
|
|
'des' => '本文档使用`Laytp极速后台开发框架 - 生成Api文档插件`进行生成。
|
|
如果需要使用本文档的在线测试功能，需要先进行Api文档配置。
|
|
|
|
### Api文档配置
|
|
点击本文档右上角配置图标会弹出配置层。
|
|
配置项包括：Api请求域名、签名开关、Header参数。
|
|
|
|
#### Api请求域名
|
|
后台使用单域名部署模式，则无需修改，使用默认值即可。
|
|
后台使用多域名部署模式，则后端程序员需要提供请求Api的域名地址。使用者不要以/结尾，将请求Api的域名地址填入此处
|
|
|
|
#### 签名开关
|
|
请求Api有签名中间件，签名中间件是否启用要根据后台[系统配置 - 基础配置 - Api签名开关]是否开启的配置来决定。如果后台配置[Api签名开关]开启了，此处也要开启。此处开启后，使用本文档的在线测试功能时，在ajax请求头部会自动添加request-time和sign两个参数。至于签名具体如何生成，请查阅[签名相关]章节说明
|
|
|
|
#### Header参数
|
|
此处填入后端程序员自定义的请求头部参数。框架自定义的请求头部参数有用户登录凭证token，请求时间戳request-time，签名sign三个。一个复杂的系统，一般还会在Header头部定义一些公用参数。比如平台标识，代理标识等等。这些公用参数根据需求不同由后端程序员定义，在使用本文档时，自行在此处进行添加
|
|
|
|
### 配置保存
|
|
点击保存按钮，或者点击页面阴影部分遮罩层，配置都会进行保存
|
|
|
|
### 配置持久化
|
|
Api文档配置使用的是localStorage存储在浏览器端进行持久化的。无需担心页面关闭后，配置不存在的问题',
|
|
'create_time' => date('Y-m-d H:i:s'),
|
|
'update_time' => date('Y-m-d H:i:s'),
|
|
],
|
|
[
|
|
'title' => '统一说明',
|
|
'des' => '# 请求方式
|
|
默认使用POST方式进行请求
|
|
|
|
# 请求头Content-Type
|
|
请求头的Content-Type定义请求参数的数据类型。ThinkPHP6兼容多种常用请求头方式。比如`application/json`、`application/form-data`和 `application/x-www-form-urlencoded`。
|
|
|
|
一般的接口，客户端可以使用`application/json`，自行将参数定义成`json`格式进行参数传递。
|
|
|
|
文件上传不支持`json`方式上传文件`Base64`内容，需要使用提交表单方式上传文件。
|
|
|
|
# 接口域名
|
|
- 正式环境
|
|
由后端程序员提供
|
|
|
|
- 测试环境
|
|
由后端程序员提供
|
|
|
|
# 后台地址
|
|
- 正式环境
|
|
- 访问地址
|
|
由后端程序员提供
|
|
- 账号
|
|
admin
|
|
- 密码
|
|
123456
|
|
- 测试环境
|
|
- 访问地址
|
|
由后端程序员提供
|
|
- 账号
|
|
admin
|
|
- 密码
|
|
123456',
|
|
'create_time' => date('Y-m-d H:i:s'),
|
|
'update_time' => date('Y-m-d H:i:s'),
|
|
],
|
|
[
|
|
'title' => '签名相关',
|
|
'des' => '客户端请求Api接口程序，后端有签名中间件对请求进行拦截。
|
|
|
|
签名中间件是否启用要根据后台[系统配置 - 基础配置 - Api签名开关]是否开启的配置来决定。
|
|
|
|
如果后台配置[Api签名开关]开启了，那么客户端在请求Api接口时，需要在Header部分传递两个参数`request-time`和`sign`。
|
|
|
|
`request-time`的值由客户端自行定义为当前Unix时间戳。
|
|
|
|
`sign`的值由签名生成规则计算生成。
|
|
|
|
# 签名生成规则
|
|
- 客户端自行定义request-time的值为当前Unix时间戳，并经过`md5`运算得到`stringA`
|
|
|
|
- 后台系统配置 - 基础配置 - Api签名Key的值为生成签名的Key，并经过`md5`运算得到`stringB`
|
|
|
|
- 连接`stringA`和`stringB`后经过`md5`运算得到`stringC`
|
|
|
|
- 最后将`stringC`全部转成大写即是客户端需要在请求头部分传递的`sign`值',
|
|
'create_time' => date('Y-m-d H:i:s'),
|
|
'update_time' => date('Y-m-d H:i:s'),
|
|
],
|
|
[
|
|
'title' => '接口返回',
|
|
'des' => '接口统一返回`json`格式的数据。
|
|
|
|
# 返回说明
|
|
|
|
|参数名|必然存在|类型|说明|
|
|
|:---- |:---|:----- |----- |
|
|
|code |是 |integer |接口返回码.0=常规正确码，表示常规操作成功；1=常规错误码，客户端仅需提示message；其他返回码与具体业务相关。框架实现了的唯一其他返回码：10401，前端需要跳转至登录界面。在一个复杂的交互过程中，你可能需要自行定义其他返回码|
|
|
|msg |是 |string | 接口返回文字描述 |
|
|
|time |是 |integer | 接口返回时间戳，单位秒 |
|
|
|data |是 |object/array | 附加数据。单条数据是对象，多条数据是数组。当为空时，会返回一个空对象{}|
|
|
|
|
# 返回示例
|
|
```
|
|
{
|
|
"code":1,
|
|
"msg":"签名错误",
|
|
"time":1613628412,
|
|
"data":{}
|
|
}
|
|
```',
|
|
'create_time' => date('Y-m-d H:i:s'),
|
|
'update_time' => date('Y-m-d H:i:s'),
|
|
],
|
|
];
|
|
|
|
$table->setData($data)->create();
|
|
}
|
|
} |