feat: add arazzo bootstrap to generate starter workflows from OpenAPI documents
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.yamlgenerates one workflow per tag, calling the tag's operations in document order. Untagged operations go in thedefaultworkflow (along with any operations taggeddefault), and an operation with several tags appears in each tag's workflow.--taglimits generation to some tags.--operations a,b,cinstead generates a single workflow calling those operations in order (--workflow-idnames it, defaultmain).--source-nameoverrides the source description name, which is otherwise derived frominfo.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), matchingopenapi spec bootstrap.
Each generated step:
- targets its operation by
operationId, or byoperationPathwhen it doesn't have one (including OpenAPI 3.2additionalOperations) - 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,enumand 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 documents2XXor 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.
--operationsis the way to describe a real flow. - Steps share the input for the same parameter (name and location), e.g.
petIdforgetPetanddeletePet. Different parameters whose names would clash, such as a pathidand a queryid, get a numbered input (id2). - Parameter names are converted to camelCase input names (
X-TracebecomesxTrace). 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,
contentparameters, unusable link values, clashing names, a realdefaulttag) and the sample.test-clidiffs the CLI output against the goldens and runsvalidateandlinton it. - Patch coverage: 100% of the library functions. The CLI gaps are
runBootstrap's os-stream wiring andfilepath.AbsandMarshalerror branches that can't fail in practice.