feat(connector-openapi): OpenAPI 3.x → Connector generator (ADR-0023)#1425
Merged
Conversation
Add @objectstack/connector-openapi, mirroring connector-rest / connector-mcp:
- createOpenApiConnector turns an OpenAPI 3.x document into a Connector
definition + handler map (one operation -> one action). It reuses
@objectstack/connector-rest's request handler for the HTTP/auth transport
(one shared implementation, per ADR-0022) and returns the same
{ definition, handlers } shape consumed by engine.registerConnector — no new
engine surface.
- Input schemas assembled as { path, query, header, body } from parameters +
requestBody; output schema from the 200/2xx/default JSON response; action
names from operationId with a deterministic slug fallback and de-duping.
- Auth inferred from components.securitySchemes when no credentials are
supplied; supplied RestAuth is reflected in the definition metadata.
- include allowlist for trimming large specs.
- registerOpenApiConnector plugin mirroring registerRestConnector /
registerMcpConnector.
- 12 unit tests (metadata, name/slug fallback, schema assembly, output schema,
auth inference, allowlist, handler path/query/body dispatch, missing-base-URL
error, engine registration).
Updates ADR-0023 status to mark the generator package implemented; the CLI and
worked example remain noted follow-ups.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Make @objectstack/connector-openapi self-contained and correct against the
real connector/spec APIs (fixes the initial scaffold):
- Drop the @objectstack/connector-rest dependency; inline the static-auth HTTP
transport (build URL, apply auth, JSON-encode body, normalise to
{ status, ok, body }) mirroring connector-rest, so the package depends only
on @objectstack/core + @objectstack/spec like every sibling connector.
- Use the real ConnectorAction `key` field, the `{ type }` auth discriminator,
import Connector from @objectstack/spec/integration, and return { def,
handlers } — matching the registry contract used by connector-rest/mcp.
- Fix tsconfig (rootDir/outDir/types) so dts builds.
Resolves the "Validate Package Dependencies" failure: add
@objectstack/connector-openapi to the changesets `fixed` group, add a changeset
entry, and refresh pnpm-lock.yaml. Update ADR-0023 to describe the
self-contained transport. Merge latest main.
Verified locally: turbo build (esm+cjs+dts), 10/10 vitest tests, eslint,
check-changeset-fixed.mjs, and pnpm install --frozen-lockfile all pass.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
|
||
| /** Build the request URL from base + path + query, encoding query params. */ | ||
| function buildUrl(baseUrl: string, path: string, query: Record<string, string>): string { | ||
| const base = baseUrl.replace(/\/+$/, ''); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the core of ADR-0023: a new open-source package
@objectstack/connector-openapithat turns a declarative OpenAPI 3.x document into aConnector— one operation → one action — plus a generic handler per action.It adds no new runtime abstraction and is self-contained (depends only on
@objectstack/core+@objectstack/spec, like every sibling connector). Each generated action drives one shared static-auth HTTP transport that mirrors@objectstack/connector-rest(build URL from base+path+query, apply static auth, JSON-encode the body, normalise the response to{ status, ok, body }). The generator returns the{ def, handlers }shape consumed byengine.registerConnector(def, handlers)— exactly like the hand-written, REST, and MCP connectors.What's in here
createOpenApiConnector— flattens paths × methods into actions; actionkey=operationIdwith a deterministic slug fallback and de-duping;inputSchemaassembled as{ path, query, header, body }fromparameters+requestBody;outputSchemafrom the200/2xx/defaultJSON response. Each handler interpolates path params and forwardsquery/header/bodythrough the shared transport.none/api-key/basic/bearer) supplied by the caller, reflected in the connector definition.includeallowlist to trim large specs to a usable subset.registerOpenApiConnectorhelper mirroring the sibling connectors' registration.@objectstack/connector-openapito the changesetsfixedgroup + a changeset entry; lockfile refreshed.Open-source / enterprise boundary (ADR-0023 §4)
Static auth only. Managed OAuth2, credential vault, per-tenant lifecycle, and curated catalogs remain enterprise (ADR-0015/0022).
Testing (all green locally)
turbo run build(esm + cjs + dts),eslint,check-changeset-fixed.mjs, andpnpm install --frozen-lockfileall clean.Remaining follow-ups (noted in the ADR)
openapi-to-connectorCLI emitting a reviewable*.connector.json(needs a multi-entry build; every connector package currently uses the shared single-entrytsupconfig).examples/(GitHub/Stripe subset).$refderef pass.https://claude.ai/code/session_01UW43Uzua3azgNKoLGkkUde