diff --git a/backend/README.md b/backend/README.md index d71096c..139b2f6 100644 --- a/backend/README.md +++ b/backend/README.md @@ -464,6 +464,27 @@ go run ./cmd/server http://localhost:3001/swagger/index.html ``` +### 9.4 生成 Swagger 文档 + +仓库根目录提供了两个脚本，方便重新生成 API 文档： + +- Linux / WSL / macOS：`./gen_swagger.sh` +- Windows PowerShell：`./gen_swagger.ps1` + +脚本会自动切换到 `backend/` 目录，并执行： + +```bash +swag init -g ./cmd/server/main.go --parseDependency --parseInternal +``` + +生成产物位于 `backend/docs/` 下： + +- `docs.go` +- `swagger.json` +- `swagger.yaml` + +如果遇到 `cannot find type definition: model.GraphData` 之类的报错，通常是 handler 文件里缺少 `internal/model` 的显式导入。 + --- ## 十、当前实现特点 diff --git a/backend/cmd/server/main.go b/backend/cmd/server/main.go index 1624f87..e2d0596 100644 --- a/backend/cmd/server/main.go +++ b/backend/cmd/server/main.go @@ -10,7 +10,7 @@ import ( swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" - "knowledge-graph-backend/docs" + _ "knowledge-graph-backend/docs" "knowledge-graph-backend/internal/config" "knowledge-graph-backend/internal/handler" neo4jClient "knowledge-graph-backend/internal/repository/neo4j" @@ -45,7 +45,6 @@ func main() { router.Use(cors.New(cfg.CORS.ToGinConfig())) - docs.SwaggerInfo.BasePath = "/" router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) // @Summary 健康检查 diff --git a/backend/docs/docs.go b/backend/docs/docs.go index 04e0d76..6bdaa92 100644 --- a/backend/docs/docs.go +++ b/backend/docs/docs.go @@ -32,7 +32,7 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/model.CreateEdgeRequest" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateEdgeRequest" } } ], @@ -40,31 +40,31 @@ const docTemplate = `{ "200": { "description": "创建成功", "schema": { - "$ref": "#/definitions/model.EdgeResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.EdgeResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "源节点或目标节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "409": { "description": "边已存在", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -90,19 +90,19 @@ const docTemplate = `{ "200": { "description": "删除成功", "schema": { - "$ref": "#/definitions/model.DeleteResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse" } }, "404": { "description": "边未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -119,13 +119,13 @@ const docTemplate = `{ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.GraphData" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.GraphData" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -142,13 +142,13 @@ const docTemplate = `{ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.SimpleGraphData" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleGraphData" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -172,7 +172,7 @@ const docTemplate = `{ "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -195,7 +195,7 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/model.CreateNodeRequest" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateNodeRequest" } } ], @@ -203,25 +203,25 @@ const docTemplate = `{ "200": { "description": "创建成功", "schema": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "409": { "description": "节点已存在", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -247,25 +247,25 @@ const docTemplate = `{ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.NodeResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.NodeResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -293,7 +293,7 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/model.UpdateNodeRequest" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.UpdateNodeRequest" } } ], @@ -301,25 +301,25 @@ const docTemplate = `{ "200": { "description": "更新成功", "schema": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -343,19 +343,19 @@ const docTemplate = `{ "200": { "description": "删除成功", "schema": { - "$ref": "#/definitions/model.DeleteResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -381,25 +381,25 @@ const docTemplate = `{ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.NeighborResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.NeighborResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -425,19 +425,19 @@ const docTemplate = `{ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.SearchResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SearchResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -445,7 +445,7 @@ const docTemplate = `{ } }, "definitions": { - "model.CreateEdgeRequest": { + "knowledge-graph-backend_internal_model.CreateEdgeRequest": { "type": "object", "required": [ "id", @@ -480,7 +480,7 @@ const docTemplate = `{ } } }, - "model.CreateNodeRequest": { + "knowledge-graph-backend_internal_model.CreateNodeRequest": { "type": "object", "required": [ "id", @@ -514,7 +514,7 @@ const docTemplate = `{ } } }, - "model.DeleteResponse": { + "knowledge-graph-backend_internal_model.DeleteResponse": { "type": "object", "properties": { "id": { @@ -531,7 +531,7 @@ const docTemplate = `{ } } }, - "model.Edge": { + "knowledge-graph-backend_internal_model.Edge": { "type": "object", "properties": { "id": { @@ -559,7 +559,7 @@ const docTemplate = `{ } } }, - "model.EdgeResponse": { + "knowledge-graph-backend_internal_model.EdgeResponse": { "type": "object", "properties": { "id": { @@ -588,52 +588,54 @@ const docTemplate = `{ } } }, - "model.ErrorResponse": { + "knowledge-graph-backend_internal_model.ErrorResponse": { "type": "object", "properties": { "error": { - "type": "string" + "type": "string", + "example": "bad_request" }, "message": { - "type": "string" + "type": "string", + "example": "invalid request" } } }, - "model.GraphData": { + "knowledge-graph-backend_internal_model.GraphData": { "type": "object", "properties": { "edges": { "type": "array", "items": { - "$ref": "#/definitions/model.Edge" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge" } }, "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } } } }, - "model.NeighborResponse": { + "knowledge-graph-backend_internal_model.NeighborResponse": { "type": "object", "properties": { "edges": { "type": "array", "items": { - "$ref": "#/definitions/model.Edge" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge" } }, "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } } } }, - "model.Node": { + "knowledge-graph-backend_internal_model.Node": { "type": "object", "properties": { "id": { @@ -661,7 +663,7 @@ const docTemplate = `{ } } }, - "model.NodeResponse": { + "knowledge-graph-backend_internal_model.NodeResponse": { "type": "object", "properties": { "id": { @@ -673,7 +675,7 @@ const docTemplate = `{ "neighbors": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "properties": { @@ -695,7 +697,7 @@ const docTemplate = `{ } } }, - "model.SearchResponse": { + "knowledge-graph-backend_internal_model.SearchResponse": { "type": "object", "properties": { "count": { @@ -704,7 +706,7 @@ const docTemplate = `{ "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "query": { @@ -712,7 +714,7 @@ const docTemplate = `{ } } }, - "model.SimpleEdge": { + "knowledge-graph-backend_internal_model.SimpleEdge": { "type": "object", "properties": { "label": { @@ -733,24 +735,24 @@ const docTemplate = `{ } } }, - "model.SimpleGraphData": { + "knowledge-graph-backend_internal_model.SimpleGraphData": { "type": "object", "properties": { "edges": { "type": "array", "items": { - "$ref": "#/definitions/model.SimpleEdge" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleEdge" } }, "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.SimpleNode" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleNode" } } } }, - "model.SimpleNode": { + "knowledge-graph-backend_internal_model.SimpleNode": { "type": "object", "properties": { "id": { @@ -767,7 +769,7 @@ const docTemplate = `{ } } }, - "model.UpdateNodeRequest": { + "knowledge-graph-backend_internal_model.UpdateNodeRequest": { "type": "object", "properties": { "label": { diff --git a/backend/docs/swagger.json b/backend/docs/swagger.json index f9b4682..d40c0f1 100644 --- a/backend/docs/swagger.json +++ b/backend/docs/swagger.json @@ -26,7 +26,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/model.CreateEdgeRequest" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateEdgeRequest" } } ], @@ -34,31 +34,31 @@ "200": { "description": "创建成功", "schema": { - "$ref": "#/definitions/model.EdgeResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.EdgeResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "源节点或目标节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "409": { "description": "边已存在", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -84,19 +84,19 @@ "200": { "description": "删除成功", "schema": { - "$ref": "#/definitions/model.DeleteResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse" } }, "404": { "description": "边未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -113,13 +113,13 @@ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.GraphData" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.GraphData" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -136,13 +136,13 @@ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.SimpleGraphData" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleGraphData" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -166,7 +166,7 @@ "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -189,7 +189,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/model.CreateNodeRequest" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateNodeRequest" } } ], @@ -197,25 +197,25 @@ "200": { "description": "创建成功", "schema": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "409": { "description": "节点已存在", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -241,25 +241,25 @@ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.NodeResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.NodeResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -287,7 +287,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/model.UpdateNodeRequest" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.UpdateNodeRequest" } } ], @@ -295,25 +295,25 @@ "200": { "description": "更新成功", "schema": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -337,19 +337,19 @@ "200": { "description": "删除成功", "schema": { - "$ref": "#/definitions/model.DeleteResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -375,25 +375,25 @@ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.NeighborResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.NeighborResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "404": { "description": "节点未找到", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -419,19 +419,19 @@ "200": { "description": "成功", "schema": { - "$ref": "#/definitions/model.SearchResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SearchResponse" } }, "400": { "description": "请求错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } }, "500": { "description": "内部错误", "schema": { - "$ref": "#/definitions/model.ErrorResponse" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse" } } } @@ -439,7 +439,7 @@ } }, "definitions": { - "model.CreateEdgeRequest": { + "knowledge-graph-backend_internal_model.CreateEdgeRequest": { "type": "object", "required": [ "id", @@ -474,7 +474,7 @@ } } }, - "model.CreateNodeRequest": { + "knowledge-graph-backend_internal_model.CreateNodeRequest": { "type": "object", "required": [ "id", @@ -508,7 +508,7 @@ } } }, - "model.DeleteResponse": { + "knowledge-graph-backend_internal_model.DeleteResponse": { "type": "object", "properties": { "id": { @@ -525,7 +525,7 @@ } } }, - "model.Edge": { + "knowledge-graph-backend_internal_model.Edge": { "type": "object", "properties": { "id": { @@ -553,7 +553,7 @@ } } }, - "model.EdgeResponse": { + "knowledge-graph-backend_internal_model.EdgeResponse": { "type": "object", "properties": { "id": { @@ -582,52 +582,54 @@ } } }, - "model.ErrorResponse": { + "knowledge-graph-backend_internal_model.ErrorResponse": { "type": "object", "properties": { "error": { - "type": "string" + "type": "string", + "example": "bad_request" }, "message": { - "type": "string" + "type": "string", + "example": "invalid request" } } }, - "model.GraphData": { + "knowledge-graph-backend_internal_model.GraphData": { "type": "object", "properties": { "edges": { "type": "array", "items": { - "$ref": "#/definitions/model.Edge" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge" } }, "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } } } }, - "model.NeighborResponse": { + "knowledge-graph-backend_internal_model.NeighborResponse": { "type": "object", "properties": { "edges": { "type": "array", "items": { - "$ref": "#/definitions/model.Edge" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge" } }, "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } } } }, - "model.Node": { + "knowledge-graph-backend_internal_model.Node": { "type": "object", "properties": { "id": { @@ -655,7 +657,7 @@ } } }, - "model.NodeResponse": { + "knowledge-graph-backend_internal_model.NodeResponse": { "type": "object", "properties": { "id": { @@ -667,7 +669,7 @@ "neighbors": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "properties": { @@ -689,7 +691,7 @@ } } }, - "model.SearchResponse": { + "knowledge-graph-backend_internal_model.SearchResponse": { "type": "object", "properties": { "count": { @@ -698,7 +700,7 @@ "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.Node" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node" } }, "query": { @@ -706,7 +708,7 @@ } } }, - "model.SimpleEdge": { + "knowledge-graph-backend_internal_model.SimpleEdge": { "type": "object", "properties": { "label": { @@ -727,24 +729,24 @@ } } }, - "model.SimpleGraphData": { + "knowledge-graph-backend_internal_model.SimpleGraphData": { "type": "object", "properties": { "edges": { "type": "array", "items": { - "$ref": "#/definitions/model.SimpleEdge" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleEdge" } }, "nodes": { "type": "array", "items": { - "$ref": "#/definitions/model.SimpleNode" + "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleNode" } } } }, - "model.SimpleNode": { + "knowledge-graph-backend_internal_model.SimpleNode": { "type": "object", "properties": { "id": { @@ -761,7 +763,7 @@ } } }, - "model.UpdateNodeRequest": { + "knowledge-graph-backend_internal_model.UpdateNodeRequest": { "type": "object", "properties": { "label": { diff --git a/backend/docs/swagger.yaml b/backend/docs/swagger.yaml index c26f216..2791be9 100644 --- a/backend/docs/swagger.yaml +++ b/backend/docs/swagger.yaml @@ -1,6 +1,6 @@ basePath: / definitions: - model.CreateEdgeRequest: + knowledge-graph-backend_internal_model.CreateEdgeRequest: properties: id: example: edge_123 @@ -26,7 +26,7 @@ definitions: - source - target type: object - model.CreateNodeRequest: + knowledge-graph-backend_internal_model.CreateNodeRequest: properties: id: example: node_123 @@ -51,7 +51,7 @@ definitions: - label - type type: object - model.DeleteResponse: + knowledge-graph-backend_internal_model.DeleteResponse: properties: id: example: node_123 @@ -63,7 +63,7 @@ definitions: example: true type: boolean type: object - model.Edge: + knowledge-graph-backend_internal_model.Edge: properties: id: type: string @@ -82,7 +82,7 @@ definitions: type: type: string type: object - model.EdgeResponse: + knowledge-graph-backend_internal_model.EdgeResponse: properties: id: example: edge_123 @@ -103,36 +103,38 @@ definitions: example: CONTAINS type: string type: object - model.ErrorResponse: + knowledge-graph-backend_internal_model.ErrorResponse: properties: error: + example: bad_request type: string message: + example: invalid request type: string type: object - model.GraphData: + knowledge-graph-backend_internal_model.GraphData: properties: edges: items: - $ref: '#/definitions/model.Edge' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Edge' type: array nodes: items: - $ref: '#/definitions/model.Node' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Node' type: array type: object - model.NeighborResponse: + knowledge-graph-backend_internal_model.NeighborResponse: properties: edges: items: - $ref: '#/definitions/model.Edge' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Edge' type: array nodes: items: - $ref: '#/definitions/model.Node' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Node' type: array type: object - model.Node: + knowledge-graph-backend_internal_model.Node: properties: id: type: string @@ -151,7 +153,7 @@ definitions: "y": type: number type: object - model.NodeResponse: + knowledge-graph-backend_internal_model.NodeResponse: properties: id: type: string @@ -159,7 +161,7 @@ definitions: type: string neighbors: items: - $ref: '#/definitions/model.Node' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Node' type: array properties: additionalProperties: true @@ -174,18 +176,18 @@ definitions: "y": type: number type: object - model.SearchResponse: + knowledge-graph-backend_internal_model.SearchResponse: properties: count: type: integer nodes: items: - $ref: '#/definitions/model.Node' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Node' type: array query: type: string type: object - model.SimpleEdge: + knowledge-graph-backend_internal_model.SimpleEdge: properties: label: example: 包含 @@ -200,18 +202,18 @@ definitions: example: CONTAINS type: string type: object - model.SimpleGraphData: + knowledge-graph-backend_internal_model.SimpleGraphData: properties: edges: items: - $ref: '#/definitions/model.SimpleEdge' + $ref: '#/definitions/knowledge-graph-backend_internal_model.SimpleEdge' type: array nodes: items: - $ref: '#/definitions/model.SimpleNode' + $ref: '#/definitions/knowledge-graph-backend_internal_model.SimpleNode' type: array type: object - model.SimpleNode: + knowledge-graph-backend_internal_model.SimpleNode: properties: id: example: "1" @@ -223,7 +225,7 @@ definitions: example: 概念 type: string type: object - model.UpdateNodeRequest: + knowledge-graph-backend_internal_model.UpdateNodeRequest: properties: label: example: 机器学习 @@ -259,30 +261,30 @@ paths: name: request required: true schema: - $ref: '#/definitions/model.CreateEdgeRequest' + $ref: '#/definitions/knowledge-graph-backend_internal_model.CreateEdgeRequest' produces: - application/json responses: "200": description: 创建成功 schema: - $ref: '#/definitions/model.EdgeResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.EdgeResponse' "400": description: 请求错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "404": description: 源节点或目标节点未找到 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "409": description: 边已存在 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 创建边 /api/edges/{id}: delete: @@ -299,15 +301,15 @@ paths: "200": description: 删除成功 schema: - $ref: '#/definitions/model.DeleteResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.DeleteResponse' "404": description: 边未找到 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 删除边 /api/graph: get: @@ -318,11 +320,11 @@ paths: "200": description: 成功 schema: - $ref: '#/definitions/model.GraphData' + $ref: '#/definitions/knowledge-graph-backend_internal_model.GraphData' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 获取图数据 /api/graph/simpleJson: get: @@ -333,11 +335,11 @@ paths: "200": description: 成功 schema: - $ref: '#/definitions/model.SimpleGraphData' + $ref: '#/definitions/knowledge-graph-backend_internal_model.SimpleGraphData' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 获取简化图数据 /api/graph/stats: get: @@ -353,7 +355,7 @@ paths: "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 获取图统计信息 /api/nodes: post: @@ -366,26 +368,26 @@ paths: name: request required: true schema: - $ref: '#/definitions/model.CreateNodeRequest' + $ref: '#/definitions/knowledge-graph-backend_internal_model.CreateNodeRequest' produces: - application/json responses: "200": description: 创建成功 schema: - $ref: '#/definitions/model.Node' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Node' "400": description: 请求错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "409": description: 节点已存在 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 创建节点 /api/nodes/{id}: delete: @@ -402,15 +404,15 @@ paths: "200": description: 删除成功 schema: - $ref: '#/definitions/model.DeleteResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.DeleteResponse' "404": description: 节点未找到 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 删除节点 get: description: 根据节点 ID 获取知识图谱中的节点详细信息 @@ -426,19 +428,19 @@ paths: "200": description: 成功 schema: - $ref: '#/definitions/model.NodeResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.NodeResponse' "400": description: 请求错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "404": description: 节点未找到 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 获取节点详情 put: consumes: @@ -455,26 +457,26 @@ paths: name: request required: true schema: - $ref: '#/definitions/model.UpdateNodeRequest' + $ref: '#/definitions/knowledge-graph-backend_internal_model.UpdateNodeRequest' produces: - application/json responses: "200": description: 更新成功 schema: - $ref: '#/definitions/model.Node' + $ref: '#/definitions/knowledge-graph-backend_internal_model.Node' "400": description: 请求错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "404": description: 节点未找到 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 更新节点 /api/nodes/{id}/neighbors: get: @@ -491,19 +493,19 @@ paths: "200": description: 成功 schema: - $ref: '#/definitions/model.NeighborResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.NeighborResponse' "400": description: 请求错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "404": description: 节点未找到 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 获取节点邻居 /api/search: get: @@ -520,14 +522,14 @@ paths: "200": description: 成功 schema: - $ref: '#/definitions/model.SearchResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.SearchResponse' "400": description: 请求错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' "500": description: 内部错误 schema: - $ref: '#/definitions/model.ErrorResponse' + $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse' summary: 搜索节点 swagger: "2.0" diff --git a/backend/internal/model/graph.go b/backend/internal/model/graph.go index bc2b7ed..5a2ef7d 100644 --- a/backend/internal/model/graph.go +++ b/backend/internal/model/graph.go @@ -83,8 +83,3 @@ type SearchResponse struct { Nodes []Node `json:"nodes"` } -// ErrorResponse represents an error response -type ErrorResponse struct { - Error string `json:"error"` - Message string `json:"message"` -} diff --git a/backend/internal/service/neo4j_fetch.go b/backend/internal/service/neo4j_fetch.go new file mode 100644 index 0000000..0450400 --- /dev/null +++ b/backend/internal/service/neo4j_fetch.go @@ -0,0 +1,31 @@ +package service + +import ( + "context" + + "github.com/neo4j/neo4j-go-driver/v5/neo4j" + + "knowledge-graph-backend/internal/model" +) + +func (s *Neo4jService) fetchNodeByID(id string) (model.Node, bool, error) { + ctx := context.Background() + result, err := neo4j.ExecuteQuery(ctx, s.driver, + `MATCH (n {id: $id}) RETURN n LIMIT 1`, + map[string]any{"id": id}, + neo4j.EagerResultTransformer, + ) + if err != nil { + return model.Node{}, false, err + } + if len(result.Records) == 0 { + return model.Node{}, false, nil + } + + v, _ := result.Records[0].Get("n") + n, ok := v.(neo4j.Node) + if !ok { + return model.Node{}, false, nil + } + return neo4jNodeToModel(n), true, nil +} diff --git a/backend/internal/service/neo4j_service.go b/backend/internal/service/neo4j_service.go new file mode 100644 index 0000000..95bffb2 --- /dev/null +++ b/backend/internal/service/neo4j_service.go @@ -0,0 +1,13 @@ +package service + +import "github.com/neo4j/neo4j-go-driver/v5/neo4j" + +// Neo4jService provides graph operations backed by Neo4j. +type Neo4jService struct { + driver neo4j.DriverWithContext +} + +// NewNeo4jService creates a new Neo4j-backed graph service. +func NewNeo4jService(driver neo4j.DriverWithContext) *Neo4jService { + return &Neo4jService{driver: driver} +} diff --git a/gen_swagger.ps1 b/gen_swagger.ps1 new file mode 100755 index 0000000..8fb17a9 --- /dev/null +++ b/gen_swagger.ps1 @@ -0,0 +1,6 @@ +$ErrorActionPreference = 'Stop' + +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +Set-Location (Join-Path $ScriptDir 'backend') + +swag init -g ./cmd/server/main.go --parseDependency --parseInternal diff --git a/gen_swagger.sh b/gen_swagger.sh new file mode 100755 index 0000000..1b13136 --- /dev/null +++ b/gen_swagger.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +cd "$SCRIPT_DIR/backend" + +swag init -g ./cmd/server/main.go --parseDependency --parseInternal --output ./docs