docs: add documentation for RESTful API usage (#412)

添加 REST API 的使用文档。

Fixes #326 
Fixes #216 


```release-note
None
```

docs/developer-guide/plugin/api-reference/ui/api-request.md

@@ -29,14 +29,14 @@ import {
 } from "@halo-dev/api-client"
 ```
 
-- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 api client。
+- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 API Client。
-- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 api client。
+- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 API Client。
-- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 api client。
+- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 API Client。
-- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 api client。
+- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 API Client。
-- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 api client，需要传入 axios 实例。
+- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 API Client，需要传入 axios 实例。
-- **createConsoleApiClient**: 用于创建 Console 接口封装的 api client，需要传入 axios 实例。
+- **createConsoleApiClient**: 用于创建 Console 接口封装的 API Client，需要传入 axios 实例。
-- **createUcApiClient**: 用于创建 UC 接口封装的 api client，需要传入 axios 实例。
+- **createUcApiClient**: 用于创建 UC 接口封装的 API Client，需要传入 axios 实例。
-- **createPublicApiClient**: 用于创建公开访问接口封装的 api client，需要传入 axios 实例。
+- **createPublicApiClient**: 用于创建公开访问接口封装的 API Client，需要传入 axios 实例。
 - **axiosInstance**: 内部默认创建的 axios 实例。
 
 ## 使用

docs/developer-guide/plugin/introduction.md

@@ -1,6 +1,6 @@
 ---
 title: 介绍
-description: 插件开发的准备工作
+description: Halo 插件机制的简介
 ---
 
 Halo 采用可插拔架构，功能模块之间耦合度低、灵活性提高，支持用户按需安装、卸载插件，操作便捷。同时提供插件开发接口以确保较高扩展性和可维护性，这个系列的文档将帮助你了解如何开发 Halo 插件。

docs/developer-guide/restful-api/api-client.md

@@ -0,0 +1,112 @@
+---
+title: API Client 请求库
+description: 介绍使用 API Client 请求库发起 API 请求的方式
+---
+
+在 2.17.0 版本中，Halo 提供了新的 `@halo-dev/api-client` JS 库，用于简化在 Halo 内部、插件的 UI 中、外部应用程序中请求 Halo 接口的逻辑。
+
+此文档将介绍如何通过 `@halo-dev/api-client` 发起 API 请求。
+
+## 安装
+
+```shell
+pnpm install @halo-dev/api-client axios
+```
+
+:::info 提示
+推荐在项目中引入 TypeScript，可以获得更好的类型提示。
+:::
+
+## 模块介绍
+
+在 `@halo-dev/api-client` 包中导出了以下模块：
+
+```ts
+import {
+  coreApiClient,
+  consoleApiClient,
+  ucApiClient,
+  publicApiClient,
+  createCoreApiClient,
+  createConsoleApiClient,
+  createUcApiClient,
+  createPublicApiClient,
+  axiosInstance
+} from "@halo-dev/api-client"
+```
+
+- **coreApiClient**: 为 Halo 所有[自定义模型](https://github.com/halo-dev/rfcs/tree/main/extension)的 CRUD 接口封装的 API Client。
+- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 API Client。
+- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 API Client。
+- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 API Client。
+- **createCoreApiClient**: 用于创建[自定义模型](https://github.com/halo-dev/rfcs/tree/main/extension)的 CRUD 接口封装的 API Client，需要传入 axios 实例。
+- **createConsoleApiClient**: 用于创建 Console 接口封装的 API Client，需要传入 axios 实例。
+- **createUcApiClient**: 用于创建 UC 接口封装的 API Client，需要传入 axios 实例。
+- **createPublicApiClient**: 用于创建公开访问接口封装的 API Client，需要传入 axios 实例。
+- **axiosInstance**: 内部默认创建的 axios 实例。
+
+## 使用
+
+### 在 Halo 插件中使用
+
+参考：[插件开发 / API 请求](../plugin/api-reference/ui/api-request.md#使用)
+
+### 在 Halo 内部使用
+
+如果需要在 Halo 核心模块中使用 `@halo-dev/api-client`，可以直接使用 `coreApiClient`、`consoleApiClient`、`ucApiClient`、`publicApiClient`，无需单独处理异常逻辑和认证逻辑。
+
+示例
+
+```ts
+import { coreApiClient } from "@halo-dev/api-client"
+
+coreApiClient.content.post.listPost().then(response => {
+  // handle response
+})
+```
+
+### 在外部程序中使用
+
+在外部程序中使用时，需要自行创建 axios 实例，并使用 `createCoreApiClient`、`createConsoleApiClient`、`createUcApiClient`、`createPublicApiClient` 创建 API Client，这样可以方便处理异常逻辑和认证逻辑。
+
+```javascript
+import axios from "axios"
+
+const axiosInstance = axios.create({
+  baseURL: "http://localhost:8090",
+  headers: {
+    // 使用个人令牌进行认证
+    Authorization: 'Bearer pat_1234567890abcdef',
+  }
+})
+
+// 添加请求拦截器
+axiosInstance.interceptors.request.use(
+  (config) => {
+    return config;
+  },
+  (error) => {
+    return Promise.reject(error);
+  }
+);
+
+// 添加响应拦截器
+axiosInstance.interceptors.response.use(
+  (response) => {
+    return response;
+  },
+  async (error: AxiosError) => {
+    // handle error
+  }
+);
+
+const coreApiClient = createCoreApiClient(axiosInstance)
+
+coreApiClient.content.post.listPost().then(response => {
+  // handle response
+})
+```
+
+:::info 提示
+认证方式的说明请参考：[认证方式](./introduction.md#认证方式)
+:::

docs/developer-guide/restful-api/introduction.md

@@ -0,0 +1,105 @@
+---
+title: 介绍
+description: 介绍 Halo 的 RESTful API 使用方式
+---
+
+Halo 提供了 RESTful 风格的 API，Halo 的前端（主要为 Console 和 UC）与后端的交互都是通过 API 完成的。
+
+此文档将介绍如何使用 Halo 提供的 RESTful API。
+
+## API 在线文档
+
+文档地址：[https://api.halo.run](https://api.halo.run)
+
+![API 文档预览](/img/developer-guide/rest-api/swagger-ui-overview.png)
+
+其中，我们为 Halo 核心模块提供了几个分组，方便开发者查看：
+
+- **Console API**：为 Console 控制台提供的自定义 API。
+- **User-center API**：为 UC 个人中心提供的自定义 API。
+- **Extension API**：核心[模型](https://github.com/halo-dev/rfcs/tree/main/extension)自动生成的 CRUD API。
+- **Public API**：公开的 API，无需认证。
+- **Aggregated API**：所有 API 的聚合。
+
+## 认证方式
+
+### 个人令牌（推荐）
+
+个人令牌是一种用于访问 Halo API 的安全凭证，你可以使用个人令牌代替您的 Halo 账户密码进行身份验证。
+
+在个人中心的**个人令牌**页面中，可以根据当前用户已有的权限创建个人令牌，创建方式可参考：[个人中心 / 个人令牌](../../user-guide/user-center.md#个人令牌)
+
+创建成功后，将会得到一个 `pat_` 开头的字符串，接下来在所需请求的请求头中添加 `Authorization` 字段，值为 `Bearer <pat>` 即可。
+
+#### 示例
+
+cURL 请求示例：
+
+```bash
+curl -X 'GET' \
+  'https://demo.halo.run/apis/content.halo.run/v1alpha1/posts' \
+  -H 'accept: */*' \
+  -H 'Authorization: Bearer pat_1234567890abcdef'
+```
+
+[Axios](https://www.axios-http.cn/) 请求示例：
+
+```javascript
+import axios from 'axios';
+
+axios.get('https://demo.halo.run/apis/content.halo.run/v1alpha1/posts', {
+  headers: {
+    Authorization: 'Bearer pat_1234567890abcdef',
+  },
+})
+.then(response => {
+  // handle response
+})
+```
+
+### Basic Auth
+
+:::warning
+通过 Basic Auth 认证将在未来的版本默认关闭，请谨慎使用。
+:::
+
+Basic Auth 是一种通过用户名和密码进行身份验证的方式，你可以使用 Halo 账户的用户名和密码进行身份验证。
+
+在请求头中添加 `Authorization` 字段，值为 `Basic <base64>` 即可，其中 `<base64>` 为 `username:password` 的 Base64 编码。
+
+#### 示例
+
+cURL 请求示例：
+
+```bash
+curl -X 'GET' \
+  'https://demo.halo.run/apis/content.halo.run/v1alpha1/posts' \
+  -H 'accept: */*' \
+  -H 'Authorization: Basic ZGVtbzpQQHNzdzByZDEyMy4u'
+```
+
+[Axios](https://www.axios-http.cn/) 请求示例：
+
+```javascript
+import axios from 'axios';
+
+axios.get('https://demo.halo.run/apis/content.halo.run/v1alpha1/posts', {
+  headers: {
+    Authorization: `Basic ${Buffer.from('demo:P@ssw0rd123..').toString('base64')}`,
+  },
+})
+.then(response => {
+  // handle response
+})
+```
+
+## 示例项目
+
+列举一些使用了 Halo RESTful API 的项目，以供参考：
+
+- [halo-sigs/attachment-upload-cli](https://github.com/halo-sigs/attachment-upload-cli)：在 Terminal 中上传文件到 Halo 并得到链接，兼容 Typora 编辑器的图片上传。
+- [halo-sigs/vscode-extension-halo](https://github.com/halo-sigs/vscode-extension-halo)：用于将 Markdown 文件发布到 Halo 的 Visual Studio Code 插件。
+- [halo-sigs/obsidian-halo](https://github.com/halo-sigs/obsidian-halo)：Obsidian 插件，用于将 Markdown 文件发布到 Halo。
+- [LetTTGACO/elog](https://github.com/LetTTGACO/elog)：开放式跨端博客解决方案，随意组合写作平台（语雀/飞书/Notion/FlowUs）和博客平台。
+- [GodlessLiu/Halo-Image-Plugin](https://github.com/GodlessLiu/Halo-Image-Plugin)：一个浏览器插件，支持在浏览器中上传图片内容到 Halo 附件。
+- [terwer/siyuan-plugin-publisher](https://github.com/terwer/siyuan-plugin-publisher)：支持将思源笔记的文章发布到 Halo。

docs/user-guide/user-center.md

@@ -31,7 +31,7 @@ description: 关于个人中心的功能说明
 
 ## 个人令牌
 
-个人令牌是一种用于访问 Halo API 的凭证，可以通过个人令牌访问 Halo 的 REST API，而无需通过用户名和密码授权。
+个人令牌是一种用于访问 Halo API 的凭证，可以通过个人令牌访问 Halo 的 RESTful API，而无需通过用户名和密码授权。
 
 ![Entry](/img/uc/uc-pat.png)
 

i18n/zh-Hans/code.json

@@ -9,10 +9,6 @@
     "message": "页面已崩溃。",
     "description": "The title of the fallback page when the page crashed"
   },
-  "theme.BackToTopButton.buttonAriaLabel": {
-    "message": "回到顶部",
-    "description": "The ARIA label for the back to top button"
-  },
   "theme.blog.archive.title": {
     "message": "历史博文",
     "description": "The page & hero title of the blog archive page"
@@ -21,6 +17,10 @@
     "message": "历史博文",
     "description": "The page & hero description of the blog archive page"
   },
+  "theme.BackToTopButton.buttonAriaLabel": {
+    "message": "回到顶部",
+    "description": "The ARIA label for the back to top button"
+  },
   "theme.blog.paginator.navAriaLabel": {
     "message": "博文列表分页导航",
     "description": "The ARIA label for the blog pagination"
@@ -69,6 +69,10 @@
     "message": "浅色模式",
     "description": "The name for the light color mode"
   },
+  "theme.docs.breadcrumbs.navAriaLabel": {
+    "message": "页面路径",
+    "description": "The ARIA label for the breadcrumbs"
+  },
   "theme.docs.DocCard.categoryDescription.plurals": {
     "message": "{count} 个项目",
     "description": "The default description for a category card in the generated index about how many items this category includes"
@@ -85,10 +89,6 @@
     "message": "下一页",
     "description": "The label used to navigate to the next doc"
   },
-  "theme.docs.breadcrumbs.navAriaLabel": {
-    "message": "页面路径",
-    "description": "The ARIA label for the breadcrumbs"
-  },
   "theme.docs.tagDocListPageTitle.nDocsTagged": {
     "message": "{count} 篇文档带有标签",
     "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
@@ -116,10 +116,6 @@
     "message": "最新版本",
     "description": "The label used for the latest version suggestion link label"
   },
-  "theme.common.headingLinkTitle": {
-    "message": "{heading}的直接链接",
-    "description": "Title for link to heading"
-  },
   "theme.common.editThisPage": {
     "message": "编辑此页",
     "description": "The link label to edit the current page"
@@ -136,14 +132,18 @@
     "message": "最后{byUser}{atDate}更新",
     "description": "The sentence used to display when a page has been last updated, and by who"
   },
-  "theme.navbar.mobileVersionsDropdown.label": {
+  "theme.common.headingLinkTitle": {
-    "message": "选择版本",
+    "message": "{heading}的直接链接",
-    "description": "The label for the navbar versions dropdown on mobile view"
+    "description": "Title for link to heading"
   },
   "theme.NotFound.title": {
     "message": "找不到页面",
     "description": "The title of the 404 page"
   },
+  "theme.navbar.mobileVersionsDropdown.label": {
+    "message": "选择版本",
+    "description": "The label for the navbar versions dropdown on mobile view"
+  },
   "theme.tags.tagsListLabel": {
     "message": "标签：",
     "description": "The label alongside a tag list"
@@ -220,13 +220,21 @@
     "message": "本页总览",
     "description": "The label used by the button on the collapsible TOC component"
   },
+  "theme.blog.post.readMore": {
+    "message": "阅读更多",
+    "description": "The label used in blog post item excerpts to link to full blog posts"
+  },
+  "theme.blog.post.readMoreLabel": {
+    "message": "阅读 {title} 的全文",
+    "description": "The ARIA label for the link to full blog posts from excerpts"
+  },
   "theme.blog.post.readingTime.plurals": {
     "message": "阅读需 {readingTime} 分钟",
     "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
   },
-  "theme.navbar.mobileLanguageDropdown.label": {
+  "theme.docs.sidebar.navAriaLabel": {
-    "message": "选择语言",
+    "message": "文档侧边栏",
-    "description": "The label for the mobile language switcher dropdown"
+    "description": "The ARIA label for the sidebar navigation"
   },
   "theme.docs.sidebar.collapseButtonTitle": {
     "message": "收起侧边栏",
@@ -236,34 +244,18 @@
     "message": "收起侧边栏",
     "description": "The title attribute for collapse button of doc sidebar"
   },
-  "theme.blog.post.readMore": {
-    "message": "阅读更多",
-    "description": "The label used in blog post item excerpts to link to full blog posts"
-  },
-  "theme.blog.post.readMoreLabel": {
-    "message": "阅读 {title} 的全文",
-    "description": "The ARIA label for the link to full blog posts from excerpts"
-  },
-  "theme.docs.sidebar.navAriaLabel": {
-    "message": "文档侧边栏",
-    "description": "The ARIA label for the sidebar navigation"
-  },
   "theme.docs.breadcrumbs.home": {
     "message": "主页面",
     "description": "The ARIA label for the home page in the breadcrumbs"
   },
-  "theme.docs.sidebar.closeSidebarButtonAriaLabel": {
+  "theme.navbar.mobileLanguageDropdown.label": {
-    "message": "关闭导航栏",
+    "message": "选择语言",
-    "description": "The ARIA label for close button of mobile sidebar"
+    "description": "The label for the mobile language switcher dropdown"
   },
   "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": {
     "message": "← 回到主菜单",
     "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)"
   },
-  "theme.docs.sidebar.toggleSidebarButtonAriaLabel": {
-    "message": "切换导航栏",
-    "description": "The ARIA label for hamburger menu button of mobile navigation"
-  },
   "theme.docs.sidebar.expandButtonTitle": {
     "message": "展开侧边栏",
     "description": "The ARIA label and title attribute for expand button of doc sidebar"
@@ -272,6 +264,14 @@
     "message": "展开侧边栏",
     "description": "The ARIA label and title attribute for expand button of doc sidebar"
   },
+  "theme.docs.sidebar.closeSidebarButtonAriaLabel": {
+    "message": "关闭导航栏",
+    "description": "The ARIA label for close button of mobile sidebar"
+  },
+  "theme.docs.sidebar.toggleSidebarButtonAriaLabel": {
+    "message": "切换导航栏",
+    "description": "The ARIA label for hamburger menu button of mobile navigation"
+  },
   "theme.ErrorPageContent.tryAgain": {
     "message": "重试",
     "description": "The label of the button to try again rendering when the React error boundary captures an error"

i18n/zh-Hans/docusaurus-plugin-content-docs/current.json

@@ -74,5 +74,9 @@
   "sidebar.developer.category.Finder API": {
     "message": "Finder API",
     "description": "The label for category Finder API in sidebar developer"
+  },
+  "sidebar.developer.category.RESTful API": {
+    "message": "RESTful API",
+    "description": "The label for category RESTful API in sidebar developer"
   }
 }

i18n/zh-Hans/docusaurus-plugin-content-docs/version-2.19.json

@@ -74,5 +74,9 @@
   "sidebar.developer.category.Finder API": {
     "message": "Finder API",
     "description": "The label for category Finder API in sidebar developer"
+  },
+  "sidebar.developer.category.RESTful API": {
+    "message": "RESTful API",
+    "description": "The label for category RESTful API in sidebar developer"
   }
 }

sidebars.js

@@ -344,12 +344,18 @@ module.exports = {
         "developer-guide/theme/code-snippets",
       ],
     },
+    {
+      type: "category",
+      label: "RESTful API",
+      link: {
+        type: "generated-index",
+      },
+      items: [
+        "developer-guide/restful-api/introduction",
+        "developer-guide/restful-api/api-client",
+      ],
+    },
     "developer-guide/form-schema",
     "developer-guide/annotations-form",
-    // {
-    //   type: "link",
-    //   label: "REST API",
-    //   href: "https://api.halo.run",
-    // },
   ],
 };

versioned_docs/version-2.17/developer-guide/plugin/api-reference/ui/api-request.md

@@ -29,14 +29,14 @@ import {
 } from "@halo-dev/api-client"
 ```
 
-- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 api client。
+- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 API Client。
-- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 api client。
+- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 API Client。
-- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 api client。
+- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 API Client。
-- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 api client。
+- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 API Client。
-- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 api client，需要传入 axios 实例。
+- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 API Client，需要传入 axios 实例。
-- **createConsoleApiClient**: 用于创建 Console 接口封装的 api client，需要传入 axios 实例。
+- **createConsoleApiClient**: 用于创建 Console 接口封装的 API Client，需要传入 axios 实例。
-- **createUcApiClient**: 用于创建 UC 接口封装的 api client，需要传入 axios 实例。
+- **createUcApiClient**: 用于创建 UC 接口封装的 API Client，需要传入 axios 实例。
-- **createPublicApiClient**: 用于创建公开访问接口封装的 api client，需要传入 axios 实例。
+- **createPublicApiClient**: 用于创建公开访问接口封装的 API Client，需要传入 axios 实例。
 - **axiosInstance**: 内部默认创建的 axios 实例。
 
 ## 使用

versioned_docs/version-2.18/developer-guide/plugin/api-reference/ui/api-request.md

@@ -29,14 +29,14 @@ import {
 } from "@halo-dev/api-client"
 ```
 
-- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 api client。
+- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 API Client。
-- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 api client。
+- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 API Client。
-- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 api client。
+- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 API Client。
-- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 api client。
+- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 API Client。
-- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 api client，需要传入 axios 实例。
+- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 API Client，需要传入 axios 实例。
-- **createConsoleApiClient**: 用于创建 Console 接口封装的 api client，需要传入 axios 实例。
+- **createConsoleApiClient**: 用于创建 Console 接口封装的 API Client，需要传入 axios 实例。
-- **createUcApiClient**: 用于创建 UC 接口封装的 api client，需要传入 axios 实例。
+- **createUcApiClient**: 用于创建 UC 接口封装的 API Client，需要传入 axios 实例。
-- **createPublicApiClient**: 用于创建公开访问接口封装的 api client，需要传入 axios 实例。
+- **createPublicApiClient**: 用于创建公开访问接口封装的 API Client，需要传入 axios 实例。
 - **axiosInstance**: 内部默认创建的 axios 实例。
 
 ## 使用

versioned_docs/version-2.19/developer-guide/plugin/api-reference/ui/api-request.md

@@ -29,14 +29,14 @@ import {
 } from "@halo-dev/api-client"
 ```
 
-- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 api client。
+- **coreApiClient**: 为 Halo 所有自定义模型的 CRUD 接口封装的 API Client。
-- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 api client。
+- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 API Client。
-- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 api client。
+- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 API Client。
-- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 api client。
+- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 API Client。
-- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 api client，需要传入 axios 实例。
+- **createCoreApiClient**: 用于创建自定义模型的 CRUD 接口封装的 API Client，需要传入 axios 实例。
-- **createConsoleApiClient**: 用于创建 Console 接口封装的 api client，需要传入 axios 实例。
+- **createConsoleApiClient**: 用于创建 Console 接口封装的 API Client，需要传入 axios 实例。
-- **createUcApiClient**: 用于创建 UC 接口封装的 api client，需要传入 axios 实例。
+- **createUcApiClient**: 用于创建 UC 接口封装的 API Client，需要传入 axios 实例。
-- **createPublicApiClient**: 用于创建公开访问接口封装的 api client，需要传入 axios 实例。
+- **createPublicApiClient**: 用于创建公开访问接口封装的 API Client，需要传入 axios 实例。
 - **axiosInstance**: 内部默认创建的 axios 实例。
 
 ## 使用

versioned_docs/version-2.19/developer-guide/plugin/introduction.md

@@ -1,6 +1,6 @@
 ---
 title: 介绍
-description: 插件开发的准备工作
+description: Halo 插件机制的简介
 ---
 
 Halo 采用可插拔架构，功能模块之间耦合度低、灵活性提高，支持用户按需安装、卸载插件，操作便捷。同时提供插件开发接口以确保较高扩展性和可维护性，这个系列的文档将帮助你了解如何开发 Halo 插件。

versioned_docs/version-2.19/developer-guide/restful-api/api-client.md

@@ -0,0 +1,112 @@
+---
+title: API Client 请求库
+description: 介绍使用 API Client 请求库发起 API 请求的方式
+---
+
+在 2.17.0 版本中，Halo 提供了新的 `@halo-dev/api-client` JS 库，用于简化在 Halo 内部、插件的 UI 中、外部应用程序中请求 Halo 接口的逻辑。
+
+此文档将介绍如何通过 `@halo-dev/api-client` 发起 API 请求。
+
+## 安装
+
+```shell
+pnpm install @halo-dev/api-client axios
+```
+
+:::info 提示
+推荐在项目中引入 TypeScript，可以获得更好的类型提示。
+:::
+
+## 模块介绍
+
+在 `@halo-dev/api-client` 包中导出了以下模块：
+
+```ts
+import {
+  coreApiClient,
+  consoleApiClient,
+  ucApiClient,
+  publicApiClient,
+  createCoreApiClient,
+  createConsoleApiClient,
+  createUcApiClient,
+  createPublicApiClient,
+  axiosInstance
+} from "@halo-dev/api-client"
+```
+
+- **coreApiClient**: 为 Halo 所有[自定义模型](https://github.com/halo-dev/rfcs/tree/main/extension)的 CRUD 接口封装的 API Client。
+- **consoleApiClient**: 为 Halo 针对 Console 提供的接口封装的 API Client。
+- **ucApiClient**: 为 Halo 针对 UC 提供的接口封装的 API Client。
+- **publicApiClient**: 为 Halo 所有公开访问的接口封装的 API Client。
+- **createCoreApiClient**: 用于创建[自定义模型](https://github.com/halo-dev/rfcs/tree/main/extension)的 CRUD 接口封装的 API Client，需要传入 axios 实例。
+- **createConsoleApiClient**: 用于创建 Console 接口封装的 API Client，需要传入 axios 实例。
+- **createUcApiClient**: 用于创建 UC 接口封装的 API Client，需要传入 axios 实例。
+- **createPublicApiClient**: 用于创建公开访问接口封装的 API Client，需要传入 axios 实例。
+- **axiosInstance**: 内部默认创建的 axios 实例。
+
+## 使用
+
+### 在 Halo 插件中使用
+
+参考：[插件开发 / API 请求](../plugin/api-reference/ui/api-request.md#使用)
+
+### 在 Halo 内部使用
+
+如果需要在 Halo 核心模块中使用 `@halo-dev/api-client`，可以直接使用 `coreApiClient`、`consoleApiClient`、`ucApiClient`、`publicApiClient`，无需单独处理异常逻辑和认证逻辑。
+
+示例
+
+```ts
+import { coreApiClient } from "@halo-dev/api-client"
+
+coreApiClient.content.post.listPost().then(response => {
+  // handle response
+})
+```
+
+### 在外部程序中使用
+
+在外部程序中使用时，需要自行创建 axios 实例，并使用 `createCoreApiClient`、`createConsoleApiClient`、`createUcApiClient`、`createPublicApiClient` 创建 API Client，这样可以方便处理异常逻辑和认证逻辑。
+
+```javascript
+import axios from "axios"
+
+const axiosInstance = axios.create({
+  baseURL: "http://localhost:8090",
+  headers: {
+    // 使用个人令牌进行认证
+    Authorization: 'Bearer pat_1234567890abcdef',
+  }
+})
+
+// 添加请求拦截器
+axiosInstance.interceptors.request.use(
+  (config) => {
+    return config;
+  },
+  (error) => {
+    return Promise.reject(error);
+  }
+);
+
+// 添加响应拦截器
+axiosInstance.interceptors.response.use(
+  (response) => {
+    return response;
+  },
+  async (error: AxiosError) => {
+    // handle error
+  }
+);
+
+const coreApiClient = createCoreApiClient(axiosInstance)
+
+coreApiClient.content.post.listPost().then(response => {
+  // handle response
+})
+```
+
+:::info 提示
+认证方式的说明请参考：[认证方式](./introduction.md#认证方式)
+:::

versioned_docs/version-2.19/developer-guide/restful-api/introduction.md

@@ -0,0 +1,105 @@
+---
+title: 介绍
+description: 介绍 Halo 的 RESTful API 使用方式
+---
+
+Halo 提供了 RESTful 风格的 API，Halo 的前端（主要为 Console 和 UC）与后端的交互都是通过 API 完成的。
+
+此文档将介绍如何使用 Halo 提供的 RESTful API。
+
+## API 在线文档
+
+文档地址：[https://api.halo.run](https://api.halo.run)
+
+![API 文档预览](/img/developer-guide/rest-api/swagger-ui-overview.png)
+
+其中，我们为 Halo 核心模块提供了几个分组，方便开发者查看：
+
+- **Console API**：为 Console 控制台提供的自定义 API。
+- **User-center API**：为 UC 个人中心提供的自定义 API。
+- **Extension API**：核心[模型](https://github.com/halo-dev/rfcs/tree/main/extension)自动生成的 CRUD API。
+- **Public API**：公开的 API，无需认证。
+- **Aggregated API**：所有 API 的聚合。
+
+## 认证方式
+
+### 个人令牌（推荐）
+
+个人令牌是一种用于访问 Halo API 的安全凭证，你可以使用个人令牌代替您的 Halo 账户密码进行身份验证。
+
+在个人中心的**个人令牌**页面中，可以根据当前用户已有的权限创建个人令牌，创建方式可参考：[个人中心 / 个人令牌](../../user-guide/user-center.md#个人令牌)
+
+创建成功后，将会得到一个 `pat_` 开头的字符串，接下来在所需请求的请求头中添加 `Authorization` 字段，值为 `Bearer <pat>` 即可。
+
+#### 示例
+
+cURL 请求示例：
+
+```bash
+curl -X 'GET' \
+  'https://demo.halo.run/apis/content.halo.run/v1alpha1/posts' \
+  -H 'accept: */*' \
+  -H 'Authorization: Bearer pat_1234567890abcdef'
+```
+
+[Axios](https://www.axios-http.cn/) 请求示例：
+
+```javascript
+import axios from 'axios';
+
+axios.get('https://demo.halo.run/apis/content.halo.run/v1alpha1/posts', {
+  headers: {
+    Authorization: 'Bearer pat_1234567890abcdef',
+  },
+})
+.then(response => {
+  // handle response
+})
+```
+
+### Basic Auth
+
+:::warning
+通过 Basic Auth 认证将在未来的版本默认关闭，请谨慎使用。
+:::
+
+Basic Auth 是一种通过用户名和密码进行身份验证的方式，你可以使用 Halo 账户的用户名和密码进行身份验证。
+
+在请求头中添加 `Authorization` 字段，值为 `Basic <base64>` 即可，其中 `<base64>` 为 `username:password` 的 Base64 编码。
+
+#### 示例
+
+cURL 请求示例：
+
+```bash
+curl -X 'GET' \
+  'https://demo.halo.run/apis/content.halo.run/v1alpha1/posts' \
+  -H 'accept: */*' \
+  -H 'Authorization: Basic ZGVtbzpQQHNzdzByZDEyMy4u'
+```
+
+[Axios](https://www.axios-http.cn/) 请求示例：
+
+```javascript
+import axios from 'axios';
+
+axios.get('https://demo.halo.run/apis/content.halo.run/v1alpha1/posts', {
+  headers: {
+    Authorization: `Basic ${Buffer.from('demo:P@ssw0rd123..').toString('base64')}`,
+  },
+})
+.then(response => {
+  // handle response
+})
+```
+
+## 示例项目
+
+列举一些使用了 Halo RESTful API 的项目，以供参考：
+
+- [halo-sigs/attachment-upload-cli](https://github.com/halo-sigs/attachment-upload-cli)：在 Terminal 中上传文件到 Halo 并得到链接，兼容 Typora 编辑器的图片上传。
+- [halo-sigs/vscode-extension-halo](https://github.com/halo-sigs/vscode-extension-halo)：用于将 Markdown 文件发布到 Halo 的 Visual Studio Code 插件。
+- [halo-sigs/obsidian-halo](https://github.com/halo-sigs/obsidian-halo)：Obsidian 插件，用于将 Markdown 文件发布到 Halo。
+- [LetTTGACO/elog](https://github.com/LetTTGACO/elog)：开放式跨端博客解决方案，随意组合写作平台（语雀/飞书/Notion/FlowUs）和博客平台。
+- [GodlessLiu/Halo-Image-Plugin](https://github.com/GodlessLiu/Halo-Image-Plugin)：一个浏览器插件，支持在浏览器中上传图片内容到 Halo 附件。
+- [terwer/siyuan-plugin-publisher](https://github.com/terwer/siyuan-plugin-publisher)：支持将思源笔记的文章发布到 Halo。

versioned_sidebars/version-2.19-sidebars.json

@@ -79,11 +79,7 @@
       "link": {
         "type": "generated-index"
       },
-      "items": [
+      "items": ["contribution/issue", "contribution/pr", "contribution/sponsor"]
-        "contribution/issue",
-        "contribution/pr",
-        "contribution/sponsor"
-      ]
     },
     "about"
   ],
@@ -264,9 +260,7 @@
           "link": {
             "type": "generated-index"
           },
-          "items": [
+          "items": ["developer-guide/plugin/examples/todolist"]
-            "developer-guide/plugin/examples/todolist"
-          ]
         }
       ]
     },
@@ -330,6 +324,17 @@
         "developer-guide/theme/code-snippets"
       ]
     },
+    {
+      "type": "category",
+      "label": "RESTful API",
+      "link": {
+        "type": "generated-index"
+      },
+      "items": [
+        "developer-guide/restful-api/introduction",
+        "developer-guide/restful-api/api-client"
+      ]
+    },
     "developer-guide/form-schema",
     "developer-guide/annotations-form"
   ]