examples/openapi/README.md

AxonHub OpenAPI 示例

这个目录展示了如何使用 genqlient 生成 Go 客户端代码，以便通过 GraphQL 调用 AxonHub 的管理接口。

简介

AxonHub 提供了一个专用的 GraphQL 端点 /openapi/v1/graphql 用于管理资源（例如通过 API 动态创建 API Key）。这个示例演示了如何生成并使用 Go 代码来集成这些功能。

目录结构

• graphql/openapi.graphql: AxonHub OpenAPI 的 GraphQL Schema 定义。
• graphql/api_key.graphql: 定义了具体的操作（Mutation/Query）。
• graphql/genqlient.yaml: genqlient 的配置文件。
• graphql/generated.go: 自动生成的 Go 客户端代码。
• main.go: 使用生成代码的示例程序。

快速开始

1. 生成代码

如果你修改了 .graphql 文件或需要重新生成代码，请运行：

# 安装工具（如果尚未安装）
go get -tool github.com/Khan/genqlient@5b0aabc933fa38078f8525e38a322d3baa78320e

# 运行生成命令
cd graphql
go run github.com/Khan/genqlient

这将会根据 graphql/*.graphql 中的定义更新 graphql/generated.go。

2. 运行示例

1. 确保 AxonHub 服务器正在运行（默认端口 8090）。
2. 获取一个具有 service_account 类型且拥有 write_api_keys 权限的 API Key。
3. 运行示例程序：

export AXONHUB_API_KEY="your_service_account_api_key"
go run main.go

使用注意点

认证与权限

• 认证: 所有的 OpenAPI 请求都必须包含 Authorization: Bearer <API_KEY> 请求头。
• Key 类型: 只有 Service Account 类型的 API Key 才能访问 OpenAPI 接口。普通的 User 类型 Key 将被拒绝。
• Scope 权限: 调用 CreateLLMAPIKey 接口需要调用方 Key 具有 write_api_keys 权限。

接口行为

• 默认权限: 通过 CreateLLMAPIKey 创建的新 Key 将默认拥有 read_channels 和 write_requests 权限，适用于常规的 LLM 调用。
• Schema 同步: 如果 AxonHub 后端的 openapi.graphql 发生了变化，你需要同步更新 graphql/openapi.graphql 并重新生成代码。
• 端点地址: 默认端点为 http://localhost:8090/openapi/v1/graphql。

常见问题

• 401 Unauthorized: 请检查你的 API Key 是否为 service_account 类型，且请求头格式是否正确（Bearer 前缀）。
• 权限拒绝 (Deny): 请检查该 Key 是否关联了 write_api_keys 权限。