308 lines
11 KiB
Python
308 lines
11 KiB
Python
import json
|
|||
|
|
import re
|
||
|
|
|
||
|
|
def clean_val(v):
|
||
|
|
if v is None:
|
||
|
|
return ""
|
||
|
|
v = str(v).strip()
|
||
|
|
if v.startswith("`") and v.endswith("`"):
|
||
|
|
v = v[1:-1].strip()
|
||
|
|
if v.startswith("**") and v.endswith("**"):
|
||
|
|
v = v[2:-2].strip()
|
||
|
|
if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
|
||
|
|
v = v[1:-1].strip()
|
||
|
|
return v
|
||
|
|
|
||
|
|
def normalize_type(t):
|
||
|
|
t = clean_val(t).lower()
|
||
|
|
if t in ["uploadfile", "file", "file (binary)", "binary"]:
|
||
|
|
return "file"
|
||
|
|
if "file" in t and "string" in t:
|
||
|
|
return "file/string"
|
||
|
|
if t in ["str", "string"]:
|
||
|
|
return "string"
|
||
|
|
if t in ["int", "integer"]:
|
||
|
|
return "integer"
|
||
|
|
if t in ["float", "number"]:
|
||
|
|
return "float"
|
||
|
|
if t in ["bool", "boolean"]:
|
||
|
|
return "boolean"
|
||
|
|
if t in ["json", "dict", "object"]:
|
||
|
|
return "json"
|
||
|
|
return t
|
||
|
|
|
||
|
|
def normalize_default(d):
|
||
|
|
d = clean_val(d)
|
||
|
|
if not d or d.lower() in ["none", "null", "none (auto-extracted)", "none (unlimited)", "none (disabled)"]:
|
||
|
|
return "none"
|
||
|
|
return d.lower()
|
||
|
|
|
||
|
|
# Load MD
|
||
|
|
with open("web/docs/FASTAPI_BACKEND_API_DOCUMENTATION.md", "r") as f:
|
||
|
|
md_text = f.read()
|
||
|
|
|
||
|
|
# Load Nexus
|
||
|
|
with open("web/docs/data.json", "r") as f:
|
||
|
|
nexus_data = json.load(f)
|
||
|
|
|
||
|
|
# Parse MD sections
|
||
|
|
md_sections = re.split(r"\n(?=###\s+)", md_text)
|
||
|
|
md_map = {} # keyed by url or key
|
||
|
|
for s in md_sections[1:]:
|
||
|
|
lines = s.strip().split("\n")
|
||
|
|
header = lines[0].replace("###", "").strip()
|
||
|
|
|
||
|
|
url_m = re.search(r"\*\*URL:\*\*\s*`([^`]+)`", s)
|
||
|
|
url = url_m.group(1).strip() if url_m else ""
|
||
|
|
|
||
|
|
subs_m = re.search(r"\*\(Sub-endpoints:\s*([^\)]+)\)\*", s)
|
||
|
|
subs = subs_m.group(1).strip() if subs_m else ""
|
||
|
|
|
||
|
|
meth_m = re.search(r"\*\*Method:\*\*\s*`?([A-Za-z0-9_\/ ]+)`?", s)
|
||
|
|
method = meth_m.group(1).strip() if meth_m else ""
|
||
|
|
|
||
|
|
# parse table
|
||
|
|
table_lines = []
|
||
|
|
in_table = False
|
||
|
|
for l in lines:
|
||
|
|
ls = l.strip()
|
||
|
|
if ls.startswith("|") and ls.endswith("|"):
|
||
|
|
in_table = True
|
||
|
|
table_lines.append(ls)
|
||
|
|
elif in_table:
|
||
|
|
break
|
||
|
|
|
||
|
|
params = []
|
||
|
|
if len(table_lines) >= 3:
|
||
|
|
raw_headers = [c.strip() for c in table_lines[0].strip("|").split("|")]
|
||
|
|
for l in table_lines[2:]:
|
||
|
|
cols = [c.strip() for c in l.strip("|").split("|")]
|
||
|
|
if len(cols) == len(raw_headers):
|
||
|
|
row = dict(zip(raw_headers, cols))
|
||
|
|
field = clean_val(row.get("Field", ""))
|
||
|
|
ty = clean_val(row.get("Type", ""))
|
||
|
|
req_raw = row.get("Required", "")
|
||
|
|
req = "req" in req_raw.lower() and "opt" not in req_raw.lower()
|
||
|
|
df = clean_val(row.get("Default", ""))
|
||
|
|
ds = row.get("Description", "")
|
||
|
|
params.append({
|
||
|
|
"name": field,
|
||
|
|
"type": ty,
|
||
|
|
"required": req,
|
||
|
|
"default": df,
|
||
|
|
"description": ds
|
||
|
|
})
|
||
|
|
|
||
|
|
md_map[header] = {
|
||
|
|
"header": header,
|
||
|
|
"url": url,
|
||
|
|
"subs": subs,
|
||
|
|
"method": method,
|
||
|
|
"params": params,
|
||
|
|
"raw_text": s
|
||
|
|
}
|
||
|
|
|
||
|
|
print(f"Parsed {len(md_map)} MD sections.")
|
||
|
|
|
||
|
|
# Map MD sections to Nexus APIs
|
||
|
|
def find_md_for_nexus_api(api, md_items):
|
||
|
|
# api has full_url, api_ip_link, path, id, title, api_key
|
||
|
|
a_url = (api.get("full_url") or "").rstrip("/")
|
||
|
|
a_link = (api.get("api_ip_link") or "").rstrip("/")
|
||
|
|
a_path = (api.get("path") or "").rstrip("/")
|
||
|
|
a_key = (api.get("api_key") or "").lower()
|
||
|
|
a_title = (api.get("title") or "").lower()
|
||
|
|
|
||
|
|
# check direct url match
|
||
|
|
for m in md_items:
|
||
|
|
m_url = m["url"].rstrip("/")
|
||
|
|
if m_url and (m_url == a_url or m_url == a_link):
|
||
|
|
return m
|
||
|
|
|
||
|
|
# check sub-endpoint full_urls
|
||
|
|
for se in api.get("endpoints", []):
|
||
|
|
se_url = (se.get("full_url") or "").rstrip("/")
|
||
|
|
for m in md_items:
|
||
|
|
m_url = m["url"].rstrip("/")
|
||
|
|
if m_url and m_url == se_url:
|
||
|
|
return m
|
||
|
|
|
||
|
|
# check path match
|
||
|
|
for m in md_items:
|
||
|
|
m_url = m["url"].rstrip("/")
|
||
|
|
if a_path and m_url.endswith(a_path):
|
||
|
|
return m
|
||
|
|
|
||
|
|
# check keyword/title match
|
||
|
|
for m in md_items:
|
||
|
|
h = m["header"].lower()
|
||
|
|
if "feedback" in a_key and "feedback" in h:
|
||
|
|
return m
|
||
|
|
if "reports" in a_key and ("telemetry" in h or "reports" in h):
|
||
|
|
return m
|
||
|
|
if "health" in a_title and "health" in h:
|
||
|
|
return m
|
||
|
|
if "waifu2x" in a_key and "gfpgan" in h:
|
||
|
|
return m
|
||
|
|
if "relight" in a_key and "relighting" in h:
|
||
|
|
return m
|
||
|
|
if "skin_analyzer" in a_path and "skin health" in h:
|
||
|
|
return m
|
||
|
|
if "trendy" in a_key and "trendy" in h:
|
||
|
|
return m
|
||
|
|
if "cartoon_model" in a_key and "3.9" in h:
|
||
|
|
return m
|
||
|
|
if "multi_segmentation" in a_key and "multi-segmentation" in h:
|
||
|
|
return m
|
||
|
|
if "hair_color_changer" in a_path and "1.1" in h:
|
||
|
|
return m
|
||
|
|
if "hair_segmentation" in a_path and "3.13" in h:
|
||
|
|
return m
|
||
|
|
return None
|
||
|
|
|
||
|
|
def compare_params(nexus_name, nexus_params, md_header, md_params, context_label=""):
|
||
|
|
diffs = []
|
||
|
|
|
||
|
|
n_param_map = {clean_val(p.get("n")): p for p in nexus_params}
|
||
|
|
m_param_map = {clean_val(p["name"]): p for p in md_params}
|
||
|
|
|
||
|
|
# check aliases in Nexus params
|
||
|
|
n_alias_map = {}
|
||
|
|
for p in nexus_params:
|
||
|
|
al = clean_val(p.get("al"))
|
||
|
|
if al:
|
||
|
|
# could be comma separated
|
||
|
|
for a in [x.strip() for x in al.split(",")]:
|
||
|
|
if a and a not in n_param_map:
|
||
|
|
n_alias_map[a] = p
|
||
|
|
|
||
|
|
all_keys = list(dict.fromkeys(list(n_param_map.keys()) + list(m_param_map.keys())))
|
||
|
|
|
||
|
|
for k in all_keys:
|
||
|
|
in_nexus = k in n_param_map
|
||
|
|
in_md = k in m_param_map
|
||
|
|
|
||
|
|
# If in MD but not directly in Nexus, check if it is an alias in Nexus
|
||
|
|
if in_md and not in_nexus and k in n_alias_map:
|
||
|
|
# Matched via alias
|
||
|
|
np = n_alias_map[k]
|
||
|
|
mp = m_param_map[k]
|
||
|
|
# Name mismatch / alias note
|
||
|
|
diffs.append({
|
||
|
|
"type": "NAME_ALIAS_DIFFERENCE",
|
||
|
|
"param": k,
|
||
|
|
"detail": f"MD uses field name '{k}', while Nexus uses primary name '{np.get('n')}' (with alias '{np.get('al')}')"
|
||
|
|
})
|
||
|
|
continue
|
||
|
|
|
||
|
|
if in_nexus and not in_md:
|
||
|
|
# Check if MD mentions this in description or table under different name
|
||
|
|
np = n_param_map[k]
|
||
|
|
diffs.append({
|
||
|
|
"type": "MISSING_IN_MD",
|
||
|
|
"param": k,
|
||
|
|
"detail": f"Shown on Nexus ({np.get('ty')}, required={np.get('rq')}, default={np.get('df')}), but MISSING from MD table"
|
||
|
|
})
|
||
|
|
continue
|
||
|
|
|
||
|
|
if in_md and not in_nexus:
|
||
|
|
mp = m_param_map[k]
|
||
|
|
diffs.append({
|
||
|
|
"type": "MISSING_ON_NEXUS",
|
||
|
|
"param": k,
|
||
|
|
"detail": f"Documented in MD ({mp.get('type')}, required={mp.get('required')}, default={mp.get('default')}), but NOT shown on Nexus"
|
||
|
|
})
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Both present: compare properties
|
||
|
|
np = n_param_map[k]
|
||
|
|
mp = m_param_map[k]
|
||
|
|
|
||
|
|
# 1. Required property
|
||
|
|
n_req = bool(np.get("rq"))
|
||
|
|
m_req = bool(mp.get("required"))
|
||
|
|
if n_req != m_req:
|
||
|
|
diffs.append({
|
||
|
|
"type": "REQUIRED_MISMATCH",
|
||
|
|
"param": k,
|
||
|
|
"detail": f"Required mismatch: Nexus has required={n_req} ('{'Required' if n_req else 'Optional'}'), but MD has required={m_req} ('{'Required' if m_req else 'Optional'}')"
|
||
|
|
})
|
||
|
|
|
||
|
|
# 2. Type property
|
||
|
|
n_ty = normalize_type(np.get("ty"))
|
||
|
|
m_ty = normalize_type(mp.get("type"))
|
||
|
|
if n_ty != m_ty:
|
||
|
|
diffs.append({
|
||
|
|
"type": "TYPE_MISMATCH",
|
||
|
|
"param": k,
|
||
|
|
"detail": f"Type mismatch: Nexus displays '{np.get('ty')}' (norm: '{n_ty}'), but MD documents '{mp.get('type')}' (norm: '{m_ty}')"
|
||
|
|
})
|
||
|
|
|
||
|
|
# 3. Default property
|
||
|
|
n_df = normalize_default(np.get("df"))
|
||
|
|
m_df = normalize_default(mp.get("default"))
|
||
|
|
if n_df != m_df:
|
||
|
|
diffs.append({
|
||
|
|
"type": "DEFAULT_MISMATCH",
|
||
|
|
"param": k,
|
||
|
|
"detail": f"Default value mismatch: Nexus displays default='{np.get('df')}', but MD documents default='{mp.get('default')}'"
|
||
|
|
})
|
||
|
|
|
||
|
|
return diffs
|
||
|
|
|
||
|
|
all_md_items = list(md_map.values())
|
||
|
|
report = []
|
||
|
|
|
||
|
|
for sec_idx, sec in enumerate(nexus_data["sections"]):
|
||
|
|
for api in sec.get("eps", []):
|
||
|
|
matched_md = find_md_for_nexus_api(api, all_md_items)
|
||
|
|
sub_eps = api.get("endpoints", [])
|
||
|
|
|
||
|
|
entry = {
|
||
|
|
"section": sec.get("title"),
|
||
|
|
"api_title": api.get("title"),
|
||
|
|
"api_key": api.get("api_key"),
|
||
|
|
"api_url": api.get("full_url"),
|
||
|
|
"md_header": matched_md["header"] if matched_md else "NO_MATCH",
|
||
|
|
"md_url": matched_md["url"] if matched_md else "",
|
||
|
|
"sub_endpoints_count": len(sub_eps),
|
||
|
|
"top_level_diffs": [],
|
||
|
|
"sub_ep_diffs": []
|
||
|
|
}
|
||
|
|
|
||
|
|
if not matched_md:
|
||
|
|
entry["top_level_diffs"].append({
|
||
|
|
"type": "NO_MD_SECTION",
|
||
|
|
"param": "N/A",
|
||
|
|
"detail": f"API exists on Nexus but has NO corresponding section in MD documentation!"
|
||
|
|
})
|
||
|
|
report.append(entry)
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Compare top-level params
|
||
|
|
n_params = api.get("params", [])
|
||
|
|
m_params = matched_md.get("params", [])
|
||
|
|
diffs = compare_params(api.get("title"), n_params, matched_md["header"], m_params, context_label="top-level")
|
||
|
|
entry["top_level_diffs"] = diffs
|
||
|
|
|
||
|
|
# For sub-endpoints, compare each sub-endpoint
|
||
|
|
if len(sub_eps) > 1:
|
||
|
|
for s_idx, se in enumerate(sub_eps):
|
||
|
|
# find if there is a specific MD section or if it uses the same MD section
|
||
|
|
se_diffs = compare_params(se.get("title") or se.get("subpath"), se.get("params", []), matched_md["header"], m_params, context_label=f"sub-ep {s_idx}")
|
||
|
|
entry["sub_ep_diffs"].append({
|
||
|
|
"sub_title": se.get("title"),
|
||
|
|
"sub_path": se.get("subpath") or se.get("path"),
|
||
|
|
"sub_url": se.get("full_url"),
|
||
|
|
"diffs": se_diffs
|
||
|
|
})
|
||
|
|
|
||
|
|
report.append(entry)
|
||
|
|
|
||
|
|
# Print summary
|
||
|
|
print("=== COMPARISON SUMMARY ===")
|
||
|
|
total_apis = len(report)
|
||
|
|
apis_with_diffs = [r for r in report if r["top_level_diffs"] or any(s["diffs"] for s in r.get("sub_ep_diffs", []))]
|
||
|
|
print(f"Total APIs checked: {total_apis}")
|
||
|
|
print(f"APIs with parameter / property differences: {len(apis_with_diffs)}")
|