openapi

package
v0.9.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

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

View Source
const (
	JavaScript = "js"
	Python     = "python"
)

Language of a generated scenario.

Variables

This section is empty.

Functions

This section is empty.

Types

type Auth added in v0.6.0

type Auth struct {
	Kind   AuthKind
	Header string // for AuthAPIKey
}

Auth describes an operation's security.

type AuthKind added in v0.6.0

type AuthKind int

AuthKind is how an operation is secured.

const (
	AuthNone AuthKind = iota
	// AuthBearer is a bearer token in the Authorization header.
	AuthBearer
	// AuthBasic is HTTP basic authentication.
	AuthBasic
	// AuthAPIKey is an API key in a header. AuthHeader names it.
	AuthAPIKey
)

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

type Spec struct {
	Title     string
	BaseURL   string
	Endpoints []Endpoint
}

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

func Parse(data []byte) (*Spec, error)

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

func (s *Spec) RenderRunbook(name string) string

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

func (s *Spec) RenderScenario(name, lang string) string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL