fix(api): add POST for hybrid-search while keeping GET compatibility (#1727)

GET with a JSON body was non-standard and confused integrators. Register
POST as the preferred method and keep GET for existing clients; update SDK,
MCP server, and API docs accordingly.

Refs: https://github.com/Tencent/WeKnora/issues/1727
This commit is contained in:
wizardchen
2026-06-22 17:20:59 +08:00
committed by lyingbug
parent 632cd55018
commit abf6a99b90
8 changed files with 1153 additions and 189 deletions
+426 -65
View File
@@ -4524,7 +4524,61 @@ const docTemplate = `{
"ApiKeyAuth": []
}
],
"description": "在知识库中执行向量和关键词混合搜索",
"description": "在知识库中执行向量和关键词混合搜索。推荐使用 POST;GET 携带 JSON 请求体仍受支持(兼容旧客户端)。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"知识库"
],
"summary": "混合搜索",
"parameters": [
{
"type": "string",
"description": "知识库ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "搜索参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams"
}
}
],
"responses": {
"200": {
"description": "搜索结果",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "请求参数错误",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
},
"post": {
"security": [
{
"Bearer": []
},
{
"ApiKeyAuth": []
}
],
"description": "在知识库中执行向量和关键词混合搜索。推荐使用 POST;GET 携带 JSON 请求体仍受支持(兼容旧客户端)。",
"consumes": [
"application/json"
],
@@ -6350,21 +6404,21 @@ const docTemplate = `{
}
}
},
"/knowledgebase/{kb_id}/wiki/categories": {
"/knowledgebase/{kb_id}/wiki/folders": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "Retrieve direct child directories for a wiki page type and optional parent_path",
"description": "Retrieve the direct child folders of a parent folder (parent_id empty = root level), each with its page count and a has-children flag for the directory tree.",
"produces": [
"application/json"
],
"tags": [
"Wiki"
],
"summary": "List wiki category paths",
"summary": "List wiki folders",
"parameters": [
{
"type": "string",
@@ -6375,27 +6429,8 @@ const docTemplate = `{
},
{
"type": "string",
"description": "Wiki page type; comma-separated for multiple (e.g. entity,concept)",
"name": "page_type",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Parent category path, slash-separated",
"name": "parent_path",
"in": "query"
},
{
"type": "integer",
"description": "Page number (1-based)",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "Page size",
"name": "page_size",
"description": "Parent folder id (empty = root)",
"name": "parent_id",
"in": "query"
}
],
@@ -6403,7 +6438,7 @@ const docTemplate = `{
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse"
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiFolderListResponse"
}
},
"400": {
@@ -6413,6 +6448,178 @@ const docTemplate = `{
}
}
}
},
"post": {
"security": [
{
"Bearer": []
}
],
"description": "Create a new (initially empty) directory node under parent_id",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Wiki"
],
"summary": "Create a wiki folder",
"parameters": [
{
"type": "string",
"description": "Knowledge base ID",
"name": "kb_id",
"in": "path",
"required": true
},
{
"description": "Folder data",
"name": "folder",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiFolderCreateRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiFolder"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/knowledgebase/{kb_id}/wiki/folders/{folder_id}": {
"put": {
"security": [
{
"Bearer": []
}
],
"description": "Rename and/or reparent a folder; the whole subtree's paths and the affected pages' cached paths are recomputed",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Wiki"
],
"summary": "Rename or move a wiki folder",
"parameters": [
{
"type": "string",
"description": "Knowledge base ID",
"name": "kb_id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Folder ID",
"name": "folder_id",
"in": "path",
"required": true
},
{
"description": "Folder update",
"name": "folder",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiFolderUpdateRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiFolder"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
},
"delete": {
"security": [
{
"Bearer": []
}
],
"description": "Delete a folder that has no pages and no child folders",
"tags": [
"Wiki"
],
"summary": "Delete an empty wiki folder",
"parameters": [
{
"type": "string",
"description": "Knowledge base ID",
"name": "kb_id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Folder ID",
"name": "folder_id",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/knowledgebase/{kb_id}/wiki/graph": {
@@ -6722,6 +6929,58 @@ const docTemplate = `{
}
}
},
"/knowledgebase/{kb_id}/wiki/move-page": {
"put": {
"security": [
{
"Bearer": []
}
],
"description": "Relocate a page (identified by slug in the body) into a folder (folder_id empty = root); the page's cached category path is recomputed",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Wiki"
],
"summary": "Move a wiki page into a folder",
"parameters": [
{
"type": "string",
"description": "Knowledge base ID",
"name": "kb_id",
"in": "path",
"required": true
},
{
"description": "Move target",
"name": "move",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiPageMoveRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiPage"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/knowledgebase/{kb_id}/wiki/pages": {
"get": {
"security": [
@@ -17163,43 +17422,6 @@ const docTemplate = `{
"WebSearchProviderTypeSearxng"
]
},
"github_com_Tencent_WeKnora_internal_types.WikiCategoryPath": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"path": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"page_size": {
"type": "integer"
},
"paths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPath"
}
},
"total": {
"type": "integer"
},
"total_pages": {
"type": "integer"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiConfig": {
"type": "object",
"properties": {
@@ -17246,6 +17468,127 @@ const docTemplate = `{
"WikiExtractionExhaustive"
]
},
"github_com_Tencent_WeKnora_internal_types.WikiFolder": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"deleted_at": {
"$ref": "#/definitions/gorm.DeletedAt"
},
"depth": {
"type": "integer"
},
"id": {
"type": "string"
},
"knowledge_base_id": {
"type": "string"
},
"name": {
"type": "string"
},
"parent_id": {
"type": "string"
},
"path": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"tenant_id": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiFolderCreateRequest": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"parent_id": {
"type": "string"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiFolderListResponse": {
"type": "object",
"properties": {
"folders": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiFolderNode"
}
},
"parent_id": {
"type": "string"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiFolderNode": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"deleted_at": {
"$ref": "#/definitions/gorm.DeletedAt"
},
"depth": {
"type": "integer"
},
"has_children": {
"type": "boolean"
},
"id": {
"type": "string"
},
"knowledge_base_id": {
"type": "string"
},
"name": {
"type": "string"
},
"page_count": {
"type": "integer"
},
"parent_id": {
"type": "string"
},
"path": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"tenant_id": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiFolderUpdateRequest": {
"type": "object",
"properties": {
"move_parent": {
"type": "boolean"
},
"name": {
"type": "string"
},
"parent_id": {
"type": "string"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiGraphData": {
"type": "object",
"properties": {
@@ -17474,7 +17817,7 @@ const docTemplate = `{
}
},
"category_path": {
"description": "CategoryPath is the directory breadcrumb that groups this page in the\nwiki browser, e.g. [\"AI\", \"LLM 应用\", \"RAG\"]. It is intentionally\nlabel-based so intermediate directory nodes do not need to be real pages.",
"description": "CategoryPath is the directory breadcrumb that groups this page in the\nwiki browser, e.g. [\"AI\", \"LLM 应用\", \"RAG\"]. Derived cache of the\nfolder chain identified by FolderID.",
"type": "array",
"items": {
"type": "string"
@@ -17507,6 +17850,10 @@ const docTemplate = `{
"description": "Depth is len(CategoryPath), cached for filtering / display.",
"type": "integer"
},
"folder_id": {
"description": "FolderID is the single source of truth for where this page sits in the\ndirectory tree — a reference to wiki_folders.id (\"\" = wiki root). The\nCategoryPath / WikiPath / Depth fields below are denormalized caches\nrecomputed from this folder's chain on every write so list/index/search\nqueries don't have to join wiki_folders.",
"type": "string"
},
"id": {
"description": "Unique identifier (UUID)",
"type": "string"
@@ -17541,7 +17888,7 @@ const docTemplate = `{
"type": "string"
},
"parent_slug": {
"description": "ParentSlug optionally points at the wiki page that should act as this\npage's semantic parent in the directory tree. The parent may be empty\nwhen the page is grouped only by CategoryPath.",
"description": "ParentSlug optionally points at the wiki page that should act as this\npage's semantic parent in the directory tree. The parent may be empty\nwhen the page is grouped only by FolderID.",
"type": "string"
},
"slug": {
@@ -17656,6 +18003,20 @@ const docTemplate = `{
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiPageMoveRequest": {
"type": "object",
"required": [
"slug"
],
"properties": {
"folder_id": {
"type": "string"
},
"slug": {
"type": "string"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiStats": {
"type": "object",
"properties": {