Commands

agent-commerce import openapi

Convert a local OpenAPI 3.x document into reviewable resource drafts.

ExperimentalHandles the shapes most REST APIs are built from and refuses the rest rather than approximating them.

Usagebash

agent-commerce import openapi <source> [options]

Arguments

<source>pathrequired

A local .yaml, .yml or .json OpenAPI 3.0, 3.1 or 3.2 document. Remote URLs are not supported.

Options

--output <path>default: <source-stem>.agent-commerce.yaml

Written in the working directory by default.

--force

Overwrite an existing output file.

--base-url <url>

Backend base URL, overriding every servers entry. Absolute http(s), no query or fragment.

--operation <id>

Import only this operation; repeatable. Matches operationId or the generated id. One that matches nothing fails the run.

--tag <tag>

Import only operations with this tag; repeatable, OR-ed.

--free

Write pricing: { type: free }.

--expose <list>

Write expose:, comma-separated from http,mcp,a2a,acp.

--strict

Any warning fails the run.

--json

A machine-readable summary instead of the report.

Examples

agent-commerce import openapi ./openapi.yaml

Reportconsole

$ agent-commerce import openapi ./openapi.yaml
OpenAPI 3.1.0: ./openapi.yaml

Imported: 12
Skipped:  1
Warnings: 3

Skipped operations:
  …

Warnings:
  …

Generated:
  openapi.agent-commerce.yaml

Pricing/exposure were not inferred.
Review the generated resources before merging them into config.yaml.

What a draft looks like

POST /users/{userId}/orders?notify=true with a JSON body becomes:

yaml

resources:
  # REVIEW: pricing and exposure are not inferred from OpenAPI. Add e.g.
  #   pricing: { type: free }
  #   expose: [http]
  createOrder:
    name: Create an order
    input:
      type: object
      properties:
        path:
          type: object
          properties:
            userId: { type: string }
          required: [userId]
          additionalProperties: false
        query:
          type: object
          properties:
            notify: { type: boolean }
          required: [notify]
          additionalProperties: false
        body:
          type: object
          properties:
            productId: { type: string }
            quantity: { type: integer }
          required: [productId]
          additionalProperties: false
      required: [path, query, body]
      additionalProperties: false
    backend:
      type: http
      method: POST
      url: https://api.example.com/users/{userId}/orders
      inputBindings:
        path: path
        query: query
        body: body

Ids come from operationId, normalised, or from <method>_<path>. They are stable across runs; two operations that resolve to the same id fail the import instead of being renamed.

Support matrix

Feature	Status
OpenAPI 3.0, 3.1, 3.2 — YAML or JSON	supported
Swagger 2.0	convert first
internal $ref	supported
external $ref, remote URL source	refused
GET, POST, PUT, PATCH, DELETE	supported
HEAD, OPTIONS, TRACE, other	skipped, warned
primitive path (simple) and query (form) parameters	supported
deepObject, object/array parameters, cookies, dynamic headers	unsupported
application/json and application/*+json bodies	supported
multipart, form-urlencoded, binary, streaming	unsupported
security credentials	never imported

A required unsupported feature skips the whole operation; an optional one is left out with a warning. Schemas keep type, properties, required, additionalProperties, enum and items; validation keywords the gateway would not enforce are dropped and listed.

Exit codes

0 on success, warnings included. 1 on a load, import or write error, an --operation that matched nothing, no supported operation imported, or any warning under --strict. A failed run writes no file.

Multi-file descriptionsBundle them first with redocly bundle or swagger-cli bundle. Re-importing overwrites and never merges, so import into a new path and diff.

agent-commerce import openapi

#Options

#Examples

#What a draft looks like

#Support matrix

#Exit codes