49 lines
1.6 KiB
Markdown
49 lines
1.6 KiB
Markdown
# OpenAPI Capability Sources
|
|
|
|
OpenAPI sources expose raw API operations as workflow capabilities.
|
|
|
|
The OpenAPI document is the source of truth for operation inventory, public
|
|
input names, JSON Schema contracts, request paths, request bodies, response
|
|
schemas, and declared status codes. Runtime execution uses a generic `httpx`
|
|
request builder plus `openapi-core` validation/unmarshalling. It does not parse
|
|
generated Python clients and does not rename public OpenAPI fields.
|
|
|
|
## Payload Shape
|
|
|
|
Workflow inputs stay OpenAPI-shaped:
|
|
|
|
```json
|
|
{
|
|
"path": {"petId": "pet-1"},
|
|
"query": {"includeOwner": true},
|
|
"header": {"X-Trace-ID": "trace-1"},
|
|
"cookie": {},
|
|
"body": {"name": "Fluffy"}
|
|
}
|
|
```
|
|
|
|
The workflow-facing field is `petId`, not a generated Python name like
|
|
`pet_id`.
|
|
|
|
## Outcomes
|
|
|
|
Raw OpenAPI nodes expose transport-level outcomes:
|
|
|
|
- `ok`: declared 2xx response and response validation passed.
|
|
- `http_error`: declared non-2xx response and response validation passed.
|
|
- `unexpected_status`: response status was not declared and no `default`
|
|
response covered it.
|
|
- `validation_error`: request or response failed OpenAPI validation.
|
|
- `transport_error`: HTTP failed before a response existed.
|
|
|
|
Business outcomes such as `not_found`, `rate_limited`, or `needs_input` belong
|
|
in saved wrappers, not raw OpenAPI operation nodes.
|
|
|
|
## Current Limits
|
|
|
|
- Auth integration is future work. For now, source configuration owns the base
|
|
URL only.
|
|
- Multipart, form, and binary request/response handling are future work.
|
|
- Rich business outcome mapping is wrapper territory.
|
|
- OpenAPI operation nodes are workflow capabilities, not top-level MCP tools.
|