Update document

2026-06-06 05:49:01 +08:00 · 2022-10-19 04:40:05 +00:00
parent 0b125fa710
commit ef88c44361
8 changed files with 165 additions and 8 deletions
--- 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
--- 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`
 * 鉴权: 需要（仅管理员）
--- 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": {
--- a/doc/api/auth/user/add.example.json
+++ 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
+    }
+}
--- a/doc/api/auth/user/add.json
+++ 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"]
+}
--- a/doc/api/auth/user/add.zh_CN.json
+++ 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"]
+}
--- a/doc/api/auth/user/user.json
+++ 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"]
+}
--- a/doc/api/auth/user/user.zh_CN.json
+++ 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"]
+}