333 lines
10 KiB
Go
333 lines
10 KiB
Go
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
|
|
}
|
|
}
|