Documentation
¶
Overview ¶
Package openapi implements FR-MCP-06's `vegaload new --from-openapi` and the generate_from_spec MCP tool: turning an OpenAPI document into a ready-to-run starting point for load testing its endpoints.
It parses JSON OpenAPI specs only — no YAML parser, deliberately, to avoid adding a new go.mod dependency (see go.mod's pinning history). Most tooling (Swagger UI, most API gateways) can export a spec as JSON even when the canonical source is YAML, so this is a real limitation but rarely a blocking one.
It writes two things. RenderScenario is a runnable scenario that calls every operation as a named step. RenderRunbook is a Markdown runbook with one `vegaload run -target ...` command per endpoint.
An OpenAPI spec describes each endpoint in isolation. It says nothing about how they relate, so the scenario's order and data flow come from simple rules, not from the spec: creates first, then reads, updates, and deletes last, and the id a create returns is used by the calls under its path. The generated file says this, and marks every value it had to guess, so the user edits it into the real flow.
Index ¶
Constants ¶
const ( JavaScript = "js" Python = "python" )
Language of a generated scenario.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Endpoint ¶
type Endpoint struct {
Method string
Path string
Summary string
// OperationID is the spec's operationId, or empty.
OperationID string
// Params are the path, query and header parameters, from the path item
// and the operation.
Params []Param
// Body is an example request body, from the spec's example or built from
// its schema. It is nil when the operation has no JSON body.
Body any
// HasBody is true when the operation has a JSON body.
HasBody bool
// OtherBody is the content type of a body that is not JSON, which a
// scenario cannot generate, or empty.
OtherBody string
// Success is the first 2xx status the spec declares, or 0.
Success int
// Auth is how the operation is secured.
Auth Auth
}
Endpoint is one operation an OpenAPI document declares: an HTTP method on a path, with its summary (when the spec provides one) for a human-readable runbook entry. The other fields are what a generated scenario needs (see RenderScenario).
type Param ¶ added in v0.6.0
type Param struct {
Name string
In string // path, query or header
Required bool
// Example is a sample value, as text. It is never empty.
Example string
// Integer is true when the schema type is integer or number.
Integer bool
}
Param is one parameter of an operation.
type Spec ¶
Spec is the minimal slice of an OpenAPI document this package needs: a title for the generated runbook's heading, a base URL to combine with each endpoint's path, and the endpoints themselves.
func Parse ¶
Parse reads an OpenAPI 3.x document from data (JSON only — see this package's doc comment) and returns the Spec RenderRunbook and RenderScenario need.
func (*Spec) RenderRunbook ¶
RenderRunbook renders a Markdown document: one `vegaload run` command per endpoint, ready to copy and run (or for an MCP-driven agent to pass straight to the run_test tool's target/protocol/executor arguments). name is used only in the heading, to connect the runbook back to the scaffold command that produced it.
func (*Spec) RenderScenario ¶ added in v0.6.0
RenderScenario writes a runnable scenario that calls every operation of the spec once per iteration, each as a named step (so the summary shows each endpoint's latency and errors, and a threshold can target one).
A spec describes each endpoint on its own, so the order and the data flow are chosen by simple rules, and the generated file says so. Creates run first, then reads, then updates, and deletes run last. When a create (POST) returns an object with an id, the calls under it (the paths that extend its own, such as /widgets/{id}) use that id. A path parameter with no create to take it from gets a placeholder, which the file marks.
lang is JavaScript or Python.