Incomex AI Portal
KB-DE90

Fix dứt điểm GPT Connector — OpenAPI Schema ↔ REST Handler Alignment — P0

8 min read Revision 1
gptconnectoropenapischemaalignmentfixp0

Fix dứt điểm GPT Connector — OpenAPI Schema ↔ REST Handler Alignment

Date: 2026-05-13 Priority: P0 Mode: Audit + Fix + Deploy Agent: Claude Code / Codex (on VPS)

Root cause confirmed

GPT Custom Action dùng OpenAPI schema để biết cách gọi REST API. Nhưng OpenAPI schema KHÔNG KHỚP với REST handlers trong server.py. Cụ thể:

  1. searchKnowledge: schema nói limit, handler expect top_k → 422
  2. createDocument: schema nói flat path/content/title/tags, handler expect structured document_id/parent_id/content/metadata → 422
  3. healthCheck: schema có thể cho phép HEAD, handler chỉ accept GET → 405

Claude MCP không bị vì MCP dùng transport riêng (/api/mcp) với tool definitions KHỚP.

Mission

Audit TỪNG operation trong OpenAPI schema vs REST handler thật. Sửa OpenAPI schema cho KHỚP 100%. Deploy. Verify.

Hard boundaries

ALLOWED:
  Đọc server.py để hiểu REST handler thật
  Đọc openapi.json/openapi.yaml hiện tại
  Sửa openapi.json/openapi.yaml CHO KHỚP với handler
  Deploy (docker compose build + up agent-data)
  Verify bằng curl

FORBIDDEN:
  Sửa REST handler logic (chỉ sửa schema cho khớp handler, KHÔNG sửa handler cho khớp schema)
  Restart containers khác (chỉ agent-data)
  Sửa MCP handler/tools (MCP đang hoạt động tốt)
  Sửa nginx config
  Sửa .env

Phase 1 — Audit

1a. Đọc REST handlers thật trong server.py

cat /opt/incomex/docker/agent-data-repo/agent_data/server.py

Cho TỪNG REST endpoint, ghi lại:

  • Route path (e.g., /chat, /health, /kb/list, /documents/...)
  • HTTP method (GET/POST)
  • Expected parameters (query params, body fields, headers)
  • Expected parameter NAMES (chính xác, case-sensitive)
  • Response format

1b. Đọc OpenAPI schema hiện tại

cat /opt/incomex/docker/nginx/static/openapi.json

hoặc:

cat /opt/incomex/docker/agent-data-repo/docs/api/openapi.yaml

Cho TỪNG operation, ghi lại:

  • operationId
  • path
  • method
  • parameters (names, types, in: query/body/header)
  • requestBody schema

1c. So sánh line-by-line

Tạo bảng so sánh:

operationId Schema path Handler path Schema method Handler method Schema params Handler params MATCH?
healthCheck ? /health ? GET ? none ?
searchKnowledge ? /chat ? POST ? message, top_k, ... ?
listDocuments ? /kb/list ? GET ? prefix, limit, offset ?
createDocument ? /documents ? POST ? document_id, parent_id, content, metadata ?
getDocument ? /documents/{id} ? GET ? document_id ?
...

Flag MỖI mismatch.

Phase 2 — Fix OpenAPI schema

Cho TỪNG mismatch tìm thấy:

  • Sửa OpenAPI schema parameter names cho KHỚP handler
  • Sửa OpenAPI schema request body structure cho KHỚP handler
  • Sửa OpenAPI schema methods cho KHỚP handler
  • KHÔNG thêm operations mới
  • KHÔNG bỏ operations đang hoạt động
  • KHÔNG sửa handler

Update TẤT CẢ copies:

  1. /opt/incomex/docker/agent-data-repo/docs/api/openapi.yaml (source)
  2. /opt/incomex/docker/nginx/static/openapi.json (served to GPT)
  3. /opt/incomex/docker/nuxt-repo/infra/nginx/static/openapi.json (repo copy)

Bump schema version: gpt-agent-data-2026-05-13.1

Phase 3 — Deploy

cd /opt/incomex/docker
docker compose build agent-data
docker compose up -d agent-data

Verify container healthy:

docker ps --filter name=agent-data --format "{{.Status}}"

Phase 4 — Verify từng endpoint bằng curl

Test CHÍNH XÁC theo OpenAPI schema mới (giống cách GPT sẽ gọi):

API_KEY=$(grep AGENT_DATA_API_KEY /opt/incomex/.env | cut -d= -f2)

# 1. healthCheck
curl -s -w "\nHTTP_CODE:%{http_code}\n" \
  https://vps.incomexsaigoncorp.vn/api/health

# 2. searchKnowledge (dùng đúng param name từ schema mới)
curl -s -w "\nHTTP_CODE:%{http_code}\n" \
  -X POST https://vps.incomexsaigoncorp.vn/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"message":"test","top_k":3}'

# 3. listDocuments
curl -s -w "\nHTTP_CODE:%{http_code}\n" \
  "https://vps.incomexsaigoncorp.vn/api/kb/list?prefix=knowledge/dev/laws/dieu44-trien-khai/notes&limit=5" \
  -H "X-API-Key: $API_KEY"

# 4. createDocument (dùng đúng structured format từ handler)
curl -s -w "\nHTTP_CODE:%{http_code}\n" \
  -X POST https://vps.incomexsaigoncorp.vn/api/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"document_id":"test/gpt-connector-verify-2026-05-13","content":"# GPT Connector Verify\nTest document for schema alignment verification.","metadata":{"title":"GPT Connector Verify Test"}}'

# 5. getDocument
curl -s -w "\nHTTP_CODE:%{http_code}\n" \
  "https://vps.incomexsaigoncorp.vn/api/documents/test/gpt-connector-verify-2026-05-13" \
  -H "X-API-Key: $API_KEY"

# 6. Verify OpenAPI schema bản mới
curl -s https://vps.incomexsaigoncorp.vn/api/openapi.json | python3 -c "
import json,sys
d=json.load(sys.stdin)
print('version:', d.get('info',{}).get('version','MISSING'))
for path, methods in d.get('paths',{}).items():
    for method, spec in methods.items():
        if isinstance(spec, dict):
            oid = spec.get('operationId','?')
            params = [p.get('name','?') for p in spec.get('parameters',[])]
            body = list(spec.get('requestBody',{}).get('content',{}).get('application/json',{}).get('schema',{}).get('properties',{}).keys()) if spec.get('requestBody') else []
            print(f'  {method.upper()} {path} → {oid} params={params} body={body}')
"

TẤT CẢ phải 200. Nếu bất kỳ endpoint nào không 200 → STOP, báo cáo.

Phase 5 — Cleanup test document + Git commit

# Xóa test document
curl -s -X DELETE "https://vps.incomexsaigoncorp.vn/api/documents/test/gpt-connector-verify-2026-05-13" \
  -H "X-API-Key: $API_KEY"

# Git commit
cd /opt/incomex/docker/agent-data-repo
git add -A
git commit -m "P0: align OpenAPI schema with REST handlers — fix GPT connector ClientResponseError"

cd /opt/incomex/docker/nuxt-repo
git add infra/nginx/static/openapi.json
git commit -m "P0: sync openapi.json with agent-data schema alignment"

Phase 6 — Report

Upload report to KB:

knowledge/current-state/reports/gpt-connector-openapi-schema-alignment-fix-2026-05-13.md

Include:

  • Full audit table (Phase 1c)
  • Every mismatch found and fixed
  • curl verification results
  • Schema version before/after
  • Git commit hashes

Final fields

audit_completed=true|false
mismatches_found=<count>
mismatches_fixed=<count>
openapi_schema_updated=true|false
schema_version=gpt-agent-data-2026-05-13.1
deploy_status=PASS|FAIL
health_check_curl=200|<other>
search_curl=200|<other>
list_curl=200|<other>
create_curl=200|<other>
get_curl=200|<other>
all_endpoints_200=true|false
git_committed=true|false
root_cause=OPENAPI_SCHEMA_REST_HANDLER_MISMATCH

SAU KHI AGENT FIX XONG

Anh Huyên cần làm 1 việc thủ công:

  1. Vào ChatGPT → GPT → Configure → Actions
  2. Xóa schema cũ
  3. Import lại từ URL: https://vps.incomexsaigoncorp.vn/api/openapi.json
  4. Save
  5. Test: gọi searchKnowledge, listDocuments, healthCheck trong GPT

Đây là bước DUY NHẤT không agent nào làm được — phải làm tay trong giao diện ChatGPT.

GPT Connector OpenAPI Schema Alignment Fix | P0 | 2026-05-13

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/prompts/gpt-connector-openapi-schema-alignment-fix-2026-05-13.md