From ef88c44361bb3a19e4149bf62659ffd2c85b39d2 Mon Sep 17 00:00:00 2001 From: lifegpc Date: Wed, 19 Oct 2022 04:40:05 +0000 Subject: [PATCH] Update document --- doc/api/auth.md | 24 ++++++++++++++++++++++++ doc/api/auth.zh_CN.md | 29 ++++++++++++++++++++++------- doc/api/auth/status.json | 2 +- doc/api/auth/user/add.example.json | 11 +++++++++++ doc/api/auth/user/add.json | 28 ++++++++++++++++++++++++++++ doc/api/auth/user/add.zh_CN.json | 28 ++++++++++++++++++++++++++++ doc/api/auth/user/user.json | 25 +++++++++++++++++++++++++ doc/api/auth/user/user.zh_CN.json | 26 ++++++++++++++++++++++++++ 8 files changed, 165 insertions(+), 8 deletions(-) create mode 100644 doc/api/auth/user/add.example.json create mode 100644 doc/api/auth/user/add.json create mode 100644 doc/api/auth/user/add.zh_CN.json create mode 100644 doc/api/auth/user/user.json create mode 100644 doc/api/auth/user/user.zh_CN.json diff --git a/doc/api/auth.md b/doc/api/auth.md index 26b5512..58b3720 100644 --- a/doc/api/auth.md +++ b/doc/api/auth.md @@ -7,3 +7,27 @@ * parameters: None * [Example](auth/status.example.json) of the response * [JSON schema](auth/status.json) of the response +## Get server public key +* route: `/auth/pubkey` or `/api/auth/pubkey` +* method: `GET` or `POST` +* auth: Not needed +* parameters: None +* [Example](auth/pubkey.example.json) of the response +* [JSON schema](auth/pubkey.json) of the response +## User management +### Add user +* route: `/auth/user/add` or `/api/auth/user/add` +* method: `GET` or `POST` +* RESTful: `PUT /api/auth/user` 或 `PUT /auth/user` +* auth: Needed (If `has_root_user` in server status is `true`, authentication is not needed. Admin privilege is needed) +* parameters: + +| Name | Type | Required | Description | +|:---:|:---:|:---:|:---:| +| `name` | `string` | Yes | User's name | +| `username` | `string` | Yes | User's name (unique and used to login) | +| `password` | `string` | Yes | User's password (RSA encrypted) | +| `is_admin` | `boolean` | No | Whether the user is an admin Default: `false`. Root user will always have admin privillege. | +| `id` | `uint64` | No | The user's id which want to be modified | +* [Example](auth/user/add.example.json) of the response +* [JSON schema](auth/user/add.json) of the response diff --git a/doc/api/auth.zh_CN.md b/doc/api/auth.zh_CN.md index 4588292..09fd962 100644 --- a/doc/api/auth.zh_CN.md +++ b/doc/api/auth.zh_CN.md @@ -11,35 +11,50 @@ * 路径: `/api/auth/pubkey`、 `/auth/pubkey` * 方法: `GET` 或 `POST` * 鉴权: 无需 -## 新增用户 +* 参数：无 +* 返回结构[示例](auth/pubkey.example.json) +* 返回结果的[JSON Schema](auth/pubkey.zh_CN.json) +## 用户管理 +### 新增用户 * 路径: `/api/auth/user/add`、 `/auth/user/add` * 方法: `GET` 或 `POST` * RESTful: `PUT /api/auth/user` 或 `PUT /auth/user` * 鉴权: 一般需要（如服务器状态内的`has_root_user`为`false`则无需鉴权，如需要仅限管理员） -## 更新用户 +* 参数： + +| 参数名 | 类型 | 必须 | 说明 | +|:---:|:---:|:---:|:---:| +| `name` | `string` | 是 | 用户名称 | +| `username` | `string` | 是 | 用户名（唯一，用于登录） | +| `password` | `string` | 是 | 用户密码（使用RSA加密） | +| `is_admin` | `boolean` | 否 | 是否为管理员。默认为`false`。root用户必定为管理员。 | +| `id` | `uint64` | 否 | 需要修改的用户ID。 | +* 返回结构[示例](auth/user/add.example.json) +* 返回结果的[JSON Schema](auth/user/add.zh_CN.json) +### 更新用户 * 路径: `/api/auth/user/update`、 `/auth/user/update` * 方法: `GET` 或 `POST` * RESTful: `PATCH /api/auth/user` 或 `PATCH /auth/user` * 鉴权: 需要（仅管理员） -## 修改用户名字 +### 修改用户名字 * 路径: `/api/auth/user/change/name`、 `/auth/user/change/name` * 方法: `GET` 或 `POST` * 鉴权: 需要 -## 修改用户密码 +### 修改用户密码 * 路径: `/api/auth/user/change/password`、 `/auth/user/change/password` * 方法: `GET` 或 `POST` * 鉴权: 需要 -## 删除用户 +### 删除用户 * 路径: `/api/auth/user/delete`、 `/auth/user/delete` * 方法: `GET` 或 `POST` * RESTful: `DELETE /api/auth/user` 或 `DELETE /auth/user` * 鉴权: 需要（仅管理员） -## 获取用户信息 +### 获取用户信息 * 路径: `/api/auth/user/info`、 `/auth/user/info` * 方法: `GET` 或 `POST` * RESTful: `GET /api/auth/user` 或 `GET /auth/user` * 鉴权: 需要（其他用户信息仅管理员） -## 获取用户列表 +### 获取用户列表 * 路径: `/api/auth/user/list`、 `/auth/user/list` * 方法: `GET` 或 `POST` * 鉴权: 需要（仅管理员） diff --git a/doc/api/auth/status.json b/doc/api/auth/status.json index 85e23ae..a1d4d54 100644 --- a/doc/api/auth/status.json +++ b/doc/api/auth/status.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema", "$id": "https://github.com/lifegpc/pixiv_downloader/raw/master/doc/api/auth/status.json", - "title": "服务器验证状态", + "title": "Server authentication status", "type": "object", "properties": { "has_root_user": { diff --git a/doc/api/auth/user/add.example.json b/doc/api/auth/user/add.example.json new file mode 100644 index 0000000..a57c23d --- /dev/null +++ b/doc/api/auth/user/add.example.json @@ -0,0 +1,11 @@ +{ + "$schema": "add.json", + "ok": true, + "code": 0, + "result": { + "id": 0, + "name": "John", + "username": "john", + "is_admin": true + } +} diff --git a/doc/api/auth/user/add.json b/doc/api/auth/user/add.json new file mode 100644 index 0000000..e2d8148 --- /dev/null +++ b/doc/api/auth/user/add.json @@ -0,0 +1,28 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "https://github.com/lifegpc/pixiv_downloader/raw/master/doc/api/auth/user/add.json", + "title": "Result object", + "type": "object", + "properties": { + "ok": { + "description": "Whether the request was successful", + "type": "boolean" + }, + "code": { + "description": "Error code, 0 if it was successful", + "type": "integer" + }, + "msg": { + "description": "Error message", + "type": "string" + }, + "debug_msg": { + "description": "Error message contains debug information" + }, + "result": { + "$ref": "user.json", + "description": "The information about the new user or modified user" + } + }, + "required": ["ok", "code"] +} diff --git a/doc/api/auth/user/add.zh_CN.json b/doc/api/auth/user/add.zh_CN.json new file mode 100644 index 0000000..ccecc9a --- /dev/null +++ b/doc/api/auth/user/add.zh_CN.json @@ -0,0 +1,28 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "https://github.com/lifegpc/pixiv_downloader/raw/master/doc/api/auth/user/add.zh_CN.json", + "title": "返回结果", + "type": "object", + "properties": { + "ok": { + "description": "请求是否成功", + "type": "boolean" + }, + "code": { + "description": "错误代码，如请求成功则为0", + "type": "integer" + }, + "msg": { + "description": "错误信息", + "type": "string" + }, + "debug_msg": { + "description": "调试用的错误信息" + }, + "result": { + "$ref": "user.zh_CN.json", + "description": "新用户/被修改用户的信息" + } + }, + "required": ["ok", "code"] +} diff --git a/doc/api/auth/user/user.json b/doc/api/auth/user/user.json new file mode 100644 index 0000000..be5d4a0 --- /dev/null +++ b/doc/api/auth/user/user.json @@ -0,0 +1,25 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "https://github.com/lifegpc/pixiv_downloader/raw/master/doc/api/auth/user/user.json", + "title": "User's information", + "properties": { + "id": { + "type": "number", + "minimum": 0, + "maximum": 18446744073709551615, + "description": "User ID" + }, + "name": { + "type": "string", + "description": "User's name" + }, + "username": { + "type": "string" + }, + "is_admin": { + "type": "boolean", + "description": "Whether the user is an admin" + } + }, + "required": ["id", "name", "username", "is_admin"] +} diff --git a/doc/api/auth/user/user.zh_CN.json b/doc/api/auth/user/user.zh_CN.json new file mode 100644 index 0000000..5c041c5 --- /dev/null +++ b/doc/api/auth/user/user.zh_CN.json @@ -0,0 +1,26 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "https://github.com/lifegpc/pixiv_downloader/raw/master/doc/api/auth/user/user.zh_CN.json", + "title": "用户信息", + "properties": { + "id": { + "type": "number", + "minimum": 0, + "maximum": 18446744073709551615, + "description": "用户ID" + }, + "name": { + "type": "string", + "description": "用户名字" + }, + "username": { + "type": "string", + "description": "用户名" + }, + "is_admin": { + "type": "boolean", + "description": "用户是否为管理员" + } + }, + "required": ["id", "name", "username", "is_admin"] +}