feat: add arazzo bootstrap to generate starter workflows from OpenAPI documents

Merged
TR
4d ago
+4285-6

Stacked on #316 (which is stacked on #315, #306 and #305). Review those first; this PR's diff is against feat/arazzo-graph.

Why

Writing an Arazzo document from scratch means copying operationIds, parameter names and locations, and request body content types out of an OpenAPI document by hand, then working out which response values feed which later call. That's the main barrier to trying Arazzo with an existing API. openapi spec bootstrap gives OpenAPI users a starting point, but there was nothing equivalent for Arazzo.

What changed

openapi arazzo bootstrap [output-file]

  • --from openapi.yaml generates one workflow per tag, calling the tag's operations in document order. Untagged operations go in the default workflow (along with any operations tagged default), and an operation with several tags appears in each tag's workflow.
  • --tag limits generation to some tags. --operations a,b,c instead generates a single workflow calling those operations in order (--workflow-id names it, default main). --source-name overrides the source description name, which is otherwise derived from info.title.
  • Without --from, it prints a hand-written example document (inputs and outputs, steps passing values to each other, success criteria, reusable parameter and failure action components), matching openapi spec bootstrap.

Each generated step:

  • targets its operation by operationId, or by operationPath when it doesn't have one (including OpenAPI 3.2 additionalOperations)
  • passes the operation's required parameters (path and item level, with operation overrides), and the request body when it's required, preferring a JSON media type
  • takes those values from workflow inputs typed from the operation's schemas (top level type, format, enum and description only, so inputs don't depend on $refs into the OpenAPI document)
  • succeeds on the operation's documented 2xx status codes ($statusCode == 201, or a regex criterion such as ^(200|202)$ for several), or any 2xx status when it documents 2XX or no 2xx codes

When an earlier step's 2xx response declares an OpenAPI link to the operation (by operationId or a local operationRef), the value comes from that step instead. Link expressions such as $response.body#/id become outputs of the earlier step and constants (including ones like $5 that aren't runtime expressions) are used as is. Values that can't be carried over, such as "pet {$response.body#/id}", fall back to an input. Outputs are only added when a later step reads them, and header names match case-insensitively.

The source description url is the OpenAPI document's path relative to the output file (or the current directory for stdout), so the result passes arazzo validate against its source and arazzo lint without changes.

The library API is arazzo.BootstrapFromOpenAPI(doc, BootstrapOptions) and arazzo.Bootstrap(), with a new example in the Arazzo README.

Review notes

  • Per-tag workflows calling every operation in document order won't always be a meaningful flow (a delete before a get, for example). They're starter material, and the CLI help and README say to review them. --operations is the way to describe a real flow.
  • Steps share the input for the same parameter (name and location), e.g. petId for getPet and deletePet. Different parameters whose names would clash, such as a path id and a query id, get a numbered input (id2).
  • Parameter names are converted to camelCase input names (X-Trace becomes xTrace). Step and workflow IDs keep values that already match [A-Za-z0-9_-]+.
  • Webhooks are skipped: they're requests the API makes to the client, so a workflow can't call them.
  • Links to other documents (./other.yaml#/...) are ignored.
  • Tests check every generated document parses with no validation errors, validates against its loaded sources, and has no findings from any lint rule. That includes the golden fixture, an edge-case document (unresolved refs, boolean schemas, content parameters, unusable link values, clashing names, a real default tag) and the sample. test-cli diffs the CLI output against the goldens and runs validate and lint on it.
  • Patch coverage: 100% of the library functions. The CLI gaps are runBootstrap's os-stream wiring and filepath.Abs and Marshal error branches that can't fail in practice.