0e78e5b06b
Backend: - ConversationTracker: Protocol + PostgresConversationTracker for lifecycle tracking - Error handler: ErrorCategory enum, classify_error(), with_retry() exponential backoff - Wire PostgresAnalyticsRecorder + ConversationTracker into ws_handler - Rate limiting (10 msg/10s per thread), edge case hardening - Health endpoint GET /api/health, version 0.5.0 - Demo seed data script + sample OpenAPI spec Frontend (all new): - React Router with NavBar (Chat / Replay / Dashboard / Review) - ReplayListPage + ReplayPage with ReplayTimeline component - DashboardPage with MetricCard, range selector, zero-state - ReviewPage for OpenAPI classification review - ErrorBanner for WebSocket disconnect handling - API client (api.ts) with typed fetch wrappers Infrastructure: - Frontend Dockerfile (multi-stage node -> nginx) - nginx.conf with SPA routing + API/WS proxy - docker-compose.yml with frontend service + healthchecks - .env.example files (root + backend) Documentation: - README.md with quick start and architecture - Agent configuration guide - OpenAPI import guide - Deployment guide - Demo script 48 new tests, 449 total passing, 92.87% coverage
107 lines
2.6 KiB
Markdown
107 lines
2.6 KiB
Markdown
# OpenAPI Auto-Discovery Guide
|
|
|
|
## Overview
|
|
|
|
Smart Support can automatically generate AI agents from any OpenAPI 3.0 specification.
|
|
Import a URL, review the AI-classified endpoints, approve, and your agents are live.
|
|
|
|
## How It Works
|
|
|
|
1. **Import** -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
|
|
2. **Parse** -- The system downloads and parses the spec.
|
|
3. **Classify** -- An LLM classifies each endpoint's:
|
|
- `access_type`: `read`, `write`, or `admin`
|
|
- `agent_group`: which specialist agent should handle this endpoint
|
|
4. **Review** -- You inspect and edit the classifications in the UI.
|
|
5. **Approve** -- Approved endpoints are registered as tools on the appropriate agents.
|
|
|
|
## Using the UI
|
|
|
|
1. Navigate to the **API Review** tab.
|
|
2. Paste your OpenAPI spec URL into the import form.
|
|
3. Click **Import**.
|
|
4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
|
|
5. Review the endpoint table:
|
|
- Edit `access_type` if the AI misclassified sensitivity.
|
|
- Edit `agent_group` to reassign an endpoint to a different agent.
|
|
6. Click **Approve & Save** when satisfied.
|
|
|
|
## Using the REST API
|
|
|
|
### Submit an import job
|
|
|
|
```http
|
|
POST /api/openapi/import
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"url": "https://api.example.com/openapi.yaml"
|
|
}
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": { "job_id": "abc123", "status": "pending" }
|
|
}
|
|
```
|
|
|
|
### Poll job status
|
|
|
|
```http
|
|
GET /api/openapi/jobs/{job_id}
|
|
```
|
|
|
|
### Get job results
|
|
|
|
```http
|
|
GET /api/openapi/jobs/{job_id}/result
|
|
```
|
|
|
|
### Approve job
|
|
|
|
```http
|
|
POST /api/openapi/jobs/{job_id}/approve
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"endpoints": [
|
|
{
|
|
"path": "/orders/{order_id}",
|
|
"method": "get",
|
|
"access_type": "read",
|
|
"agent_group": "order_agent"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Access Type Classification
|
|
|
|
| Access Type | Description | Interrupt Required |
|
|
|-------------|-------------|-------------------|
|
|
| `read` | GET operations, no side effects | No |
|
|
| `write` | POST/PUT/PATCH that modify data | Yes |
|
|
| `admin` | DELETE, bulk operations, sensitive writes | Yes |
|
|
|
|
## SSRF Protection
|
|
|
|
All import requests are validated against an allowlist:
|
|
- Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
|
|
- Localhost and metadata service URLs are blocked
|
|
- Only `http://` and `https://` schemes are permitted
|
|
|
|
To allow internal URLs (e.g., in development), set `SSRF_ALLOWLIST_HOSTS` in your environment.
|
|
|
|
## Supported Spec Formats
|
|
|
|
- OpenAPI 3.0.x (JSON or YAML)
|
|
- Swagger 2.0 is not supported
|
|
|
|
## Limitations
|
|
|
|
- Maximum spec file size: 1 MB
|
|
- Maximum endpoints per spec: 200
|
|
- Specs requiring authentication headers are not yet supported for import
|