f0699436c5
- API versioning: all REST endpoints prefixed with /api/v1/ - Structured logging: replaced stdlib logging with structlog (console/JSON modes) - Alembic migrations: versioned DB schema with initial migration - Error standardization: global exception handlers for consistent envelope format - Interrupt cleanup: asyncio background task for expired interrupt removal - Integration tests: +30 tests (analytics, replay, openapi, error, session APIs) - Frontend tests: +57 tests (all components, pages, useWebSocket hook) - Backend: 557 tests, 89.75% coverage | Frontend: 80 tests, 16 test files
131 lines
3.3 KiB
Markdown
131 lines
3.3 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` or `write`
|
|
- `needs_interrupt`: whether human approval is required
|
|
- `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 **Scan Tools**.
|
|
4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
|
|
5. Review the endpoint cards grouped by agent:
|
|
- Edit `access_type` (Read Only / Write) if the AI misclassified sensitivity.
|
|
- Edit the agent assignment to reassign an endpoint to a different agent.
|
|
6. Click **Save Configuration** 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 (202):
|
|
```json
|
|
{
|
|
"job_id": "abc123",
|
|
"status": "pending",
|
|
"spec_url": "https://api.example.com/openapi.yaml",
|
|
"total_endpoints": 0,
|
|
"classified_count": 0,
|
|
"error_message": null
|
|
}
|
|
```
|
|
|
|
### Poll job status
|
|
|
|
```http
|
|
GET /api/openapi/jobs/{job_id}
|
|
```
|
|
|
|
### Get classifications
|
|
|
|
```http
|
|
GET /api/openapi/jobs/{job_id}/classifications
|
|
```
|
|
|
|
Response: array of classification objects with `index`, `access_type`,
|
|
`needs_interrupt`, `agent_group`, `confidence`, `customer_params`, and `endpoint`.
|
|
|
|
### Update a classification
|
|
|
|
```http
|
|
PUT /api/openapi/jobs/{job_id}/classifications/{index}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"access_type": "write",
|
|
"needs_interrupt": true,
|
|
"agent_group": "order_actions"
|
|
}
|
|
```
|
|
|
|
### Approve job
|
|
|
|
```http
|
|
POST /api/openapi/jobs/{job_id}/approve
|
|
```
|
|
|
|
No request body. Generates tool code for each classified endpoint and produces
|
|
an agent YAML configuration. Response includes `generated_tools_count`.
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"job_id": "abc123",
|
|
"status": "approved",
|
|
"spec_url": "https://api.example.com/openapi.yaml",
|
|
"total_endpoints": 5,
|
|
"classified_count": 5,
|
|
"error_message": null,
|
|
"generated_tools_count": 5
|
|
}
|
|
```
|
|
|
|
## Access Type Classification
|
|
|
|
| Access Type | Description | Interrupt Required |
|
|
|-------------|-------------|-------------------|
|
|
| `read` | GET operations, no side effects | No |
|
|
| `write` | POST/PUT/PATCH/DELETE that modify data | Yes (by default) |
|
|
|
|
The `needs_interrupt` flag can be overridden per-endpoint during review.
|
|
|
|
## SSRF Protection
|
|
|
|
All import requests are validated:
|
|
- Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
|
|
- Localhost and cloud metadata service URLs are blocked
|
|
- Only `http://` and `https://` schemes are permitted
|
|
|
|
## 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
|