docs(fusion): rigorous openapi.yaml — round-trip /tokenize + /restore

Replace wholesale with strict schemas: required fields, descriptions, examples,
additionalProperties:false so Fusion treats responses as closed structured
objects. /tokenize documents the full round-trip shape (final, deidentified_prompt,
agent_tokenized, session_id); /restore is {session_id,text} -> {final,restored}.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

fusion/openapi.yaml

@@ -1,82 +1,82 @@
-openapi: 3.0.3
+openapi: 3.0.0
 info:
-  title: HNCB De-identification API (tokenize / restore)
+  title: HNCB De-identification API (via Fusion)
   version: 1.0.0
   description: |
-    Ingress/egress transforms for the reversible PII de-identification round trip.
+    Fusion-facing contract for the reversible PII de-identification demo.
 
-    Two access paths:
-    - **Direct to the backend** (`hncb-deid.apim-apac-demo.com`): the caller MUST send
-      the `x-api-key` shared secret (this spec's `ApiKeyAuth`).
-    - **Via Fusion** (the gateway listener): the gateway injects `x-api-key` on the
-      backend leg, so the portal/UI caller sends only the JSON body — no key. For that
-      path, treat the security requirement as satisfied by the gateway.
+    - POST /tokenize  — full round trip: de-identify → agent reasons on tokens → restore.
+    - POST /restore   — re-identify a tokenized text on its own (egress-only).
+
+    Callers hit the Fusion listener and send only the JSON body; Fusion injects the
+    backend `x-api-key`. Direct calls to the backend require `x-api-key` (see ApiKeyAuth).
+
+    Note: if /tokenize already returns `final`, a standalone /restore is only needed
+    when the flow is split into ingress-only tokenize + egress restore.
 
 servers:
-  - url: https://hncb-deid.apim-apac-demo.com
-    description: Backend (custom domain) — requires x-api-key
   - url: https://aus-design.sandbox.fusion.services.axway.com:4443
-    description: Fusion listener — gateway injects the key; send body only
-
-# Backend-direct requirement. Fusion callers omit the header (the gateway adds it).
-security:
-  - ApiKeyAuth: []
+    description: Fusion listener — send body only; gateway injects the key
+  - url: https://hncb-deid.apim-apac-demo.com
+    description: Backend (custom domain) — direct calls require x-api-key
 
 paths:
   /tokenize:
     post:
-      summary: Tokenize a query (de-identify PII before it leaves for the cloud)
-      operationId: tokenizeQuery
+      summary: De-identify a query, reason on tokens, and restore identity (round trip)
+      operationId: deidentifyRoundTrip
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
+              additionalProperties: false
               required:
                 - query
               properties:
                 query:
                   type: string
+                  description: Advisor's natural-language query (may contain PII).
                   example: 請幫我整理王小明最近三個月的理財往來，並給我下次拜訪話術。
       responses:
         "200":
-          description: Successful tokenization response
+          description: OK
           content:
             application/json:
               schema:
                 type: object
+                additionalProperties: false
+                required:
+                  - final
+                  - deidentified_prompt
+                  - agent_tokenized
+                  - session_id
                 properties:
+                  final:
+                    type: string
+                    description: Restored answer shown to the advisor (identity re-attached).
+                    example: "（客戶：王小明）\n根據最近90天的客戶往來紀錄，以下是建議的拜訪話術重點：…"
                   deidentified_prompt:
                     type: string
-                    description: The query with PII replaced by tokens.
+                    description: Tokenized prompt sent to the cloud (PII replaced by tokens).
                     example: 請幫我整理CUST_264978最近三個月的理財往來，並給我下次拜訪話術。
+                  agent_tokenized:
+                    type: string
+                    description: The agent's talking points — tokens only, no PII.
+                    example: "根據客戶近期活動分析，以下是建議的拜訪話術重點：…"
                   session_id:
                     type: string
-                    description: Correlates this request's tokens for later /restore.
+                    description: Vault session correlating this request's tokens.
                     example: 9d15023985154d79a477d4e5b8b2c87c
-                  tokens:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        token:
-                          type: string
-                          example: CUST_264978
-                        type:
-                          type: string
-                          description: Entity type detected (PERSON, TW_ROC_ID).
-                          example: PERSON
         "400":
           description: Missing/invalid body (query required)
         "401":
-          description: Unauthorized (missing/invalid API key)
-        "502":
-          description: Detector unavailable
+          description: Unauthorized (backend-direct call without a valid x-api-key)
 
   /restore:
     post:
-      summary: Restore (detokenize) identity in a tokenized response
+      summary: Restore (detokenize) identity in a tokenized text
       operationId: restoreIdentity
       requestBody:
         required: true
@@ -84,6 +84,7 @@ paths:
           application/json:
             schema:
               type: object
+              additionalProperties: false
               required:
                 - session_id
                 - text
@@ -98,18 +99,20 @@ paths:
                   example: 針對客戶 CUST_264978 的保守型投資組合，建議…
       responses:
         "200":
-          description: Successful restore response
+          description: OK
           content:
             application/json:
               schema:
                 type: object
+                additionalProperties: false
+                required:
+                  - final
+                  - restored
                 properties:
                   final:
                     type: string
                     description: Text with identity re-attached (envelope + inline tokens).
-                    example: |
-                      （客戶：王小明）
-                      針對客戶 王小明 的保守型投資組合，建議…
+                    example: "（客戶：王小明）\n針對客戶 王小明 的保守型投資組合，建議…"
                   restored:
                     type: integer
                     description: Number of tokens restored for this session.
@@ -117,7 +120,7 @@ paths:
         "400":
           description: Missing session_id or text
         "401":
-          description: Unauthorized (missing/invalid API key)
+          description: Unauthorized (backend-direct call without a valid x-api-key)
 
 components:
   securitySchemes:
@@ -126,5 +129,5 @@ components:
       in: header
       name: x-api-key
       description: |
-        Shared secret (`tokenize_api_key`). Required for direct backend calls;
-        injected by Fusion on the gateway path.
+        Shared secret (`tokenize_api_key`) for direct backend calls; Fusion injects
+        it on the gateway path, so Fusion-facing callers omit it.