OpenAPI Plugin

Relevant source files

• e2e/scenarios/microsoft-graph-full.test.ts
• e2e/scenarios/openapi-multi-key-auth-ui.test.ts
• packages/plugins/google/src/react/AddGoogleSource.tsx
• packages/plugins/graphql/src/react/AddGraphqlSource.tsx
• packages/plugins/mcp/src/react/AddMcpSource.tsx
• packages/plugins/microsoft/src/react/AddMicrosoftSource.tsx
• packages/plugins/microsoft/src/sdk/plugin.ts
• packages/plugins/openapi/src/api/group.ts
• packages/plugins/openapi/src/api/handlers.ts
• packages/plugins/openapi/src/react/AddOpenApiSource.tsx
• packages/plugins/openapi/src/sdk/__snapshots__/real-specs.test.ts.snap
• packages/plugins/openapi/src/sdk/backing.ts
• packages/plugins/openapi/src/sdk/client-credentials-oauth.test.ts
• packages/plugins/openapi/src/sdk/definitions.ts
• packages/plugins/openapi/src/sdk/derive-auth.ts
• packages/plugins/openapi/src/sdk/extract.test.ts
• packages/plugins/openapi/src/sdk/extract.ts
• packages/plugins/openapi/src/sdk/index.test.ts
• packages/plugins/openapi/src/sdk/index.ts
• packages/plugins/openapi/src/sdk/invoke.ts
• packages/plugins/openapi/src/sdk/multi-scope-bearer.test.ts
• packages/plugins/openapi/src/sdk/multi-scope-oauth.test.ts
• packages/plugins/openapi/src/sdk/non-json-body.test.ts
• packages/plugins/openapi/src/sdk/oauth-refresh.test.ts
• packages/plugins/openapi/src/sdk/openapi-utils.ts
• packages/plugins/openapi/src/sdk/parse.test.ts
• packages/plugins/openapi/src/sdk/parse.ts
• packages/plugins/openapi/src/sdk/preview-oauth2.test.ts
• packages/plugins/openapi/src/sdk/preview.ts
• packages/plugins/openapi/src/sdk/real-specs.test.ts
• packages/plugins/openapi/src/sdk/store.ts
• packages/plugins/openapi/src/sdk/types.ts

The OpenAPI plugin provides the integration layer for RESTful services defined by OpenAPI 3.x specifications. It handles the lifecycle of an API integration from specification parsing and tool extraction to authenticated execution and health monitoring.

Overview and Purpose

The plugin transforms static OpenAPI documents into executable tools. It manages:

• Spec Parsing: Fetching and validating YAML/JSON specifications packages/plugins/openapi/src/sdk/parse.ts1-10
• Tool Extraction: Mapping HTTP operations to discrete tools packages/plugins/openapi/src/sdk/extract.ts25-40
• Auth Detection: Automatically identifying security schemes (OAuth2, API Key, Bearer) to generate authentication templates packages/plugins/openapi/src/sdk/derive-auth.ts50-51
• Invocation Pipeline: Handling parameter binding, path resolution, and non-JSON body encoding (Multipart, XML, etc.) packages/plugins/openapi/src/sdk/invoke.ts77-127

Sources: packages/plugins/openapi/src/sdk/index.ts1-46 packages/plugins/openapi/src/sdk/plugin.ts39-46

---

Tool Extraction and Spec Parsing

The plugin extracts tools by traversing the paths object of an OpenAPI document. Each operationId (or a derived slug from the method and path) becomes a tool name.

Data Flow: Spec to Tool

1. Fetch: The fetchSpecText function retrieves the document from a URL or blob packages/plugins/openapi/src/sdk/parse.ts1-10
2. Parse: The parse function validates the document structure packages/plugins/openapi/src/sdk/parse.ts1-10
3. Extract: extract iterates over HTTP methods (GET, POST, etc.) to build ExtractedOperation objects packages/plugins/openapi/src/sdk/extract.ts46-55
4. Store: Operations are persisted in the OpenapiStore to avoid re-parsing during invocation packages/plugins/openapi/src/sdk/store.ts12-25

Code Entity Mapping: Extraction Pipeline

System Name	Code Entity	Role
Spec Parser	parse	Validates OpenAPI 3.x syntax packages/plugins/openapi/src/sdk/parse.ts1-10
Operation Binder	OperationBinding	Holds the method, path template, and parameters packages/plugins/openapi/src/sdk/types.ts168-175
Plugin Store	OpenapiStore	Manages persistence of extracted operations packages/plugins/openapi/src/sdk/store.ts102-140

Sources: packages/plugins/openapi/src/sdk/extract.ts1-40 packages/plugins/openapi/src/sdk/store.ts49-58

---

Invocation Pipeline

The invocation pipeline transforms a tool call into a physical HTTP request.

Path and Parameter Resolution

The resolvePath function performs RFC 3986 template expansion packages/plugins/openapi/src/sdk/invoke.ts77-82 It supports:

• Reserved Character Awareness: Handles allowReserved flags for path parameters packages/plugins/openapi/src/sdk/invoke.ts46-58
• Container Lookup: Parameters can be passed directly or within containers like pathParams or queryParams packages/plugins/openapi/src/sdk/invoke.ts21-41

Body Handling

The plugin supports complex request body encodings beyond standard JSON:

• Multipart/Form-Data: Encodes objects and files into multipart boundaries packages/plugins/openapi/src/sdk/non-json-body.test.ts161-186
• XML/Text: Passes string payloads with appropriate Content-Type headers packages/plugins/openapi/src/sdk/invoke.ts168-178
• Binary: Supports application/octet-stream for raw data transfer packages/plugins/openapi/src/sdk/invoke.ts179-180

Invocation Logic Diagram

This diagram shows how invokeOpenApiBackedTool coordinates with the SDK's HTTP utilities.

Sources: packages/plugins/openapi/src/sdk/invoke.ts77-145 packages/plugins/openapi/src/sdk/backing.ts17-36

---

Authentication and OAuth Refresh

The plugin uses an "Auth Template" system to handle various security requirements.

Detection and Templates

During integration registration, detectedAuthenticationTemplates scans the spec's securitySchemes packages/plugins/openapi/src/react/AddOpenApiSource.tsx50-51

• API Key: Generates an ApiKeyAuthTemplate defining where the key (header/query) should be placed packages/plugins/openapi/src/sdk/types.ts3-8
• OAuth2: Supports authorizationCode and clientCredentials flows packages/plugins/openapi/src/sdk/preview.ts46-65

Token Refresh

For OAuth2 connections, the plugin handles automatic token refresh. When an invocation fails with a 401, the pipeline uses the refreshUrl (or the tokenUrl fallback) to obtain new credentials before retrying the request packages/plugins/openapi/src/sdk/preview.ts120-145

Sources: packages/plugins/openapi/src/sdk/types.ts11-24 packages/plugins/openapi/src/sdk/config.ts48-55

---

Health Check Configuration

Health checks allow the system to verify connection viability. The plugin provides a list of HealthCheckCandidate operations packages/plugins/openapi/src/sdk/preview.ts5-8

• Selection Logic: Operations are ranked based on their safety. GET requests without required parameters are preferred packages/plugins/openapi/src/sdk/preview.ts17-20
• Identity Fields: For APIs returning collections, the UI allows selecting an "Identity Field" (e.g., id, email) to confirm the authenticated subject packages/plugins/openapi/src/react/AddOpenApiSource.tsx123-125

Sources: packages/plugins/openapi/src/sdk/backing.ts18-26 packages/plugins/openapi/src/sdk/preview.ts22-33

---

React UI: AddOpenApiSource

The AddOpenApiSource component provides a progressive form for registering new integrations.

Registration Lifecycle

1. Analysis: Debounced spec analysis triggered by URL input packages/plugins/openapi/src/react/AddOpenApiSource.tsx135-143
2. Preview: Displays SpecPreviewSummary, including detected tools and auth methods packages/plugins/openapi/src/react/AddOpenApiSource.tsx104-109
3. Configuration: Users can override the baseUrl, edit the description, and refine the authenticationTemplate packages/plugins/openapi/src/react/AddOpenApiSource.tsx147-175
4. Persistence: Calls addOpenApiSpec (via an Effect atom) to register the integration and compile tool definitions packages/plugins/openapi/src/react/AddOpenApiSource.tsx128

UI Component Architecture

Sources: packages/plugins/openapi/src/react/AddOpenApiSource.tsx92-130 packages/plugins/openapi/src/react/auth-method-config.ts39-43