REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/components/schemas/diag/StructuredDiagRequest.yaml

@@ -0,0 +1,46 @@
+type: object
+description: |
+  Structured data diagnosis request - analyze and understand structured data formats.
+
+  Operations: detect-type, generate-descriptor, diagnose, schema-selection
+required:
+  - operation
+  - sample
+properties:
+  operation:
+    type: string
+    enum:
+      - detect-type
+      - generate-descriptor
+      - diagnose
+      - schema-selection
+    description: |
+      Diagnosis operation:
+      - `detect-type`: Identify data format (CSV, JSON, XML)
+      - `generate-descriptor`: Create schema descriptor for data
+      - `diagnose`: Full analysis (detect + generate descriptor)
+      - `schema-selection`: Find matching schemas for data
+  sample:
+    type: string
+    description: Data sample to analyze (text content)
+    example: |
+      name,age,email
+      Alice,30,alice@example.com
+      Bob,25,bob@example.com
+  type:
+    type: string
+    description: Data type (required for generate-descriptor)
+    enum: [csv, json, xml]
+    example: csv
+  schema-name:
+    type: string
+    description: Target schema name for descriptor generation (optional)
+    example: person-records
+  options:
+    type: object
+    description: Format-specific options (e.g., CSV delimiter)
+    additionalProperties:
+      type: string
+    example:
+      delimiter: ","
+      has_header: "true"

specs/api/components/schemas/diag/StructuredDiagResponse.yaml

@@ -0,0 +1,49 @@
+type: object
+description: Structured data diagnosis response
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    description: Operation that was performed
+    example: diagnose
+  detected-type:
+    type: string
+    description: Detected data format (for detect-type/diagnose)
+    enum: [csv, json, xml]
+    example: csv
+  confidence:
+    type: number
+    description: Detection confidence score (0.0-1.0)
+    minimum: 0.0
+    maximum: 1.0
+    example: 0.95
+  descriptor:
+    type: object
+    description: Generated schema descriptor (for generate-descriptor/diagnose)
+    additionalProperties: {}
+    example:
+      schema_name: person-records
+      type: csv
+      fields:
+        - name: name
+          type: string
+        - name: age
+          type: integer
+        - name: email
+          type: string
+  metadata:
+    type: object
+    description: Additional analysis metadata
+    additionalProperties:
+      type: string
+    example:
+      field_count: "3"
+      record_count: "2"
+      has_header: "true"
+  schema-matches:
+    type: array
+    description: Matching schema IDs (for schema-selection)
+    items:
+      type: string
+    example: ["person-schema-v1", "contact-schema-v2"]