halo/docs
1
0
Fork 0
mirror of https://github.com/halo-dev/docs.git synced 2025-10-20 01:17:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
添加 REST API 的使用文档。

Fixes #326 
Fixes #216 


```release-note
None
```
This commit is contained in:
Ryan Wang
2024-09-09 17:34:05 +08:00
committed by GitHub
parent 3aadde1218
commit 5608dedd2b
17 changed files with 538 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

2
docs/developer-guide/plugin/introduction.md
View File

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

112
docs/developer-guide/restful-api/api-client.md Normal file
View File

@@ -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#认证方式)
:::

105
docs/developer-guide/restful-api/introduction.md Normal file
View File

@@ -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。