package docs_test import ( "encoding/json" "os" "strings" "testing" docs "github.com/Tencent/WeKnora/docs" "gopkg.in/yaml.v3" ) type swaggerDocumentCase struct { name string loadSpec func(t *testing.T) []byte parse func([]byte, any) error } type swaggerParameter struct { Name string `json:"name" yaml:"name"` In string `json:"in" yaml:"in"` Type string `json:"type" yaml:"type"` Required bool `json:"required" yaml:"required"` } type swaggerOperation struct { Parameters []swaggerParameter `json:"parameters" yaml:"parameters"` } func swaggerDocuments() []swaggerDocumentCase { return []swaggerDocumentCase{ { name: "registered document", loadSpec: func(t *testing.T) []byte { t.Helper() return []byte(docs.SwaggerInfo.ReadDoc()) }, parse: json.Unmarshal, }, { name: "swagger.json", loadSpec: func(t *testing.T) []byte { t.Helper() return readSwaggerFile(t, "swagger.json") }, parse: json.Unmarshal, }, { name: "swagger.yaml", loadSpec: func(t *testing.T) []byte { t.Helper() return readSwaggerFile(t, "swagger.yaml") }, parse: yaml.Unmarshal, }, } } func TestKnowledgeSearchRouteContract(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { assertKnowledgeSearchRouteContract(t, tt.loadSpec(t), tt.parse) }) } } func TestReleaseAPIContracts(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { var spec struct { BasePath string `json:"basePath" yaml:"basePath"` Paths map[string]map[string]any `json:"paths" yaml:"paths"` Definitions map[string]struct { Properties map[string]struct { Type string `json:"type" yaml:"type"` } `json:"properties" yaml:"properties"` } `json:"definitions" yaml:"definitions"` } if err := tt.parse(tt.loadSpec(t), &spec); err != nil { t.Fatal(err) } if spec.BasePath != "/api/v1" { t.Fatalf("unexpected API base path %q", spec.BasePath) } for path := range spec.Paths { if strings.HasPrefix(path, spec.BasePath+"/") { t.Errorf("route %s repeats the API base path", path) } } for path, methods := range map[string][]string{ "/knowledge/{id}/spans": {"get"}, "/knowledge-bases/{id}/images": {"get", "post"}, "/wiki-search": {"post"}, "/agents/tools": {"get"}, "/system/admin/users": {"get"}, "/system/admin/users/status": {"post"}, "/system/admin/model-catalog": {"get", "put"}, "/system/admin/model-catalog/preview": {"post"}, } { for _, method := range methods { if _, ok := spec.Paths[path][method]; !ok { t.Errorf("missing %s %s", method, path) } } } for _, name := range []string{"CatalogUpdate", "CatalogState", "CatalogRevision"} { definition := "github_com_Tencent_WeKnora_internal_application_service." + name if spec.Definitions[definition].Properties["overlay"].Type != "object" { t.Errorf("%s.overlay must be a JSON object", name) } } }) } } func TestGraphSearchContract(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { var spec struct { Paths map[string]map[string]any `json:"paths" yaml:"paths"` Definitions map[string]struct { Properties map[string]any `json:"properties" yaml:"properties"` } `json:"definitions" yaml:"definitions"` } if err := tt.parse(tt.loadSpec(t), &spec); err != nil { t.Fatal(err) } methods := spec.Paths["/knowledge-bases/{id}/graph-search"] if methods["post"] == nil || len(methods) != 1 { t.Fatal("graph-search must be documented as a POST-only endpoint") } const prefix = "github_com_Tencent_WeKnora_internal_types." for definition, fields := range map[string][]string{ "GraphSearchResult": {"entities", "relationships", "source_chunks", "meta"}, "GraphSearchEntity": {"id", "knowledge_id", "source_chunk_ids"}, "GraphSearchRelation": {"source_id", "target_id", "source_chunk_ids"}, "GraphSearchSourceChunk": {"content_truncated", "title_truncated"}, "GraphSearchMeta": {"truncated", "truncation_reasons"}, } { properties := spec.Definitions[prefix+definition].Properties for _, field := range fields { if properties[field] == nil { t.Errorf("%s.%s must be documented", definition, field) } } for _, hidden := range []string{"tenant_id", "knowledge_base_id", "element_id"} { if definition != "GraphSearchResult" && properties[hidden] != nil { t.Errorf("%s leaks internal field %s", definition, hidden) } } } }) } } func TestModelDeleteUsageContract(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { assertModelDeleteUsageContract(t, tt.loadSpec(t), tt.parse) }) } } func TestFAQEnabledFilterContract(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { assertFAQEnabledFilterContract(t, tt.loadSpec(t), tt.parse) }) } } func TestWikiPageBacklinkTitlesContract(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { var spec struct { Paths map[string]map[string]struct { Responses map[string]struct { Schema struct { Ref string `json:"$ref" yaml:"$ref"` } `json:"schema" yaml:"schema"` } `json:"responses" yaml:"responses"` } `json:"paths" yaml:"paths"` Definitions map[string]struct { Properties map[string]map[string]any `json:"properties" yaml:"properties"` } `json:"definitions" yaml:"definitions"` } if err := tt.parse(tt.loadSpec(t), &spec); err != nil { t.Fatal(err) } const detail = "github_com_Tencent_WeKnora_internal_types.WikiPageDetail" get := spec.Paths["/knowledgebase/{kb_id}/wiki/pages/{slug}"]["get"] if get.Responses["200"].Schema.Ref != "#/definitions/"+detail { t.Fatal("page detail response must expose backlink titles") } properties := spec.Definitions[detail].Properties titles := properties["in_link_titles"] values, ok := titles["additionalProperties"].(map[string]any) if titles["type"] != "object" || !ok || values["type"] != "string" { t.Fatal("in_link_titles must be a string-valued map") } for field := range spec.Definitions["github_com_Tencent_WeKnora_internal_types.WikiPage"].Properties { if _, ok := properties[field]; !ok { t.Errorf("page detail dropped existing field %s", field) } } if _, ok := spec.Paths["/knowledgebase/{kb_id}/wiki/page-titles"]; ok { t.Fatal("obsolete standalone title endpoint remains documented") } }) } } func readSwaggerFile(t *testing.T, name string) []byte { t.Helper() data, err := os.ReadFile(name) if err != nil { t.Fatalf("read %s: %v", name, err) } return data } func assertKnowledgeSearchRouteContract(t *testing.T, data []byte, parse func([]byte, any) error) { t.Helper() var spec struct { Paths map[string]map[string]any `json:"paths" yaml:"paths"` } if err := parse(data, &spec); err != nil { t.Fatalf("parse generated Swagger document: %v", err) } knowledgeSearch, ok := spec.Paths["/knowledge-search"] if !ok { t.Fatal("generated Swagger document does not expose /knowledge-search") } if _, ok := knowledgeSearch["post"]; !ok { t.Fatal("generated Swagger document does not expose POST /knowledge-search") } if staleRoute, ok := spec.Paths["/sessions/search"]; ok { if _, ok := staleRoute["post"]; ok { t.Fatal("generated Swagger document still exposes stale POST /sessions/search") } } } func assertModelDeleteUsageContract(t *testing.T, data []byte, parse func([]byte, any) error) { t.Helper() var spec struct { Paths map[string]map[string]struct { Responses map[string]any `json:"responses" yaml:"responses"` } `json:"paths" yaml:"paths"` Definitions map[string]map[string]any `json:"definitions" yaml:"definitions"` } if err := parse(data, &spec); err != nil { t.Fatalf("parse generated Swagger document: %v", err) } models, ok := spec.Paths["/models/{id}"] if !ok { t.Fatal("generated Swagger document does not expose /models/{id}") } deleteOperation, ok := models["delete"] if !ok { t.Fatal("generated Swagger document does not expose DELETE /models/{id}") } if _, ok := deleteOperation.Responses["400"]; !ok { t.Fatal("model DELETE Swagger contract does not document the model-in-use 400 response") } const errorCodeDefinition = "github_com_Tencent_WeKnora_internal_errors.ErrorCode" errorCodes, ok := spec.Definitions[errorCodeDefinition] if !ok { t.Fatalf("generated Swagger document does not expose %s", errorCodeDefinition) } enum, ok := errorCodes["enum"].([]any) if !ok { t.Fatalf("generated Swagger ErrorCode enum has unexpected shape: %#v", errorCodes["enum"]) } enumVarNames, ok := errorCodes["x-enum-varnames"].([]any) if !ok { t.Fatalf("generated Swagger ErrorCode names have unexpected shape: %#v", errorCodes["x-enum-varnames"]) } for i, value := range enum { if swaggerInteger(value) == 2300 { if i >= len(enumVarNames) || enumVarNames[i] != "ErrModelInUse" { t.Fatalf("error code 2300 must align with ErrModelInUse, got names=%v", enumVarNames) } return } } t.Fatal("generated Swagger ErrorCode enum does not include model-in-use code 2300") } func assertFAQEnabledFilterContract(t *testing.T, data []byte, parse func([]byte, any) error) { t.Helper() var spec struct { Paths map[string]map[string]swaggerOperation `json:"paths" yaml:"paths"` } if err := parse(data, &spec); err != nil { t.Fatalf("parse generated Swagger document: %v", err) } faqEntries, ok := spec.Paths["/knowledge-bases/{id}/faq/entries"] if !ok { t.Fatal("generated Swagger document does not expose FAQ entries route") } getOperation, ok := faqEntries["get"] if !ok { t.Fatal("generated Swagger document does not expose GET FAQ entries") } for _, parameter := range getOperation.Parameters { if parameter.Name != "is_enabled" { continue } if parameter.In != "query" || parameter.Type != "boolean" || parameter.Required { t.Fatalf("is_enabled must be an optional boolean query parameter, got %#v", parameter) } return } t.Fatal("GET FAQ entries does not document the is_enabled query parameter") } func swaggerInteger(value any) int { switch number := value.(type) { case int: return number case float64: return int(number) default: return 0 } }