openapi

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 27, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package openapi validates responses against an OpenAPI 3.x description (the engine.ResponseValidator of --openapi) and generates request files from one (sonde import openapi).

Index

Constants

View Source
const (
	GroupTag  = "tag"
	GroupPath = "path"
	GroupFlat = "flat"
)

Grouping values of GenerateOptions.Group.

View Source
const MaxSpecBytes = 64 << 20

MaxSpecBytes caps a spec file and each file it references.

Variables

This section is empty.

Functions

func Example

func Example(ref *openapi3.SchemaRef) any

Example returns a deterministic instance of the schema: its example (or first `examples` entry, const, default or first enum value), else a minimal instance built from its type: required properties only, one array item (or minItems), the first oneOf/anyOf branch, bounds and string formats honored.

Types

type GenerateOptions

type GenerateOptions struct {
	// Group lays files out: in a directory per first tag (GroupTag), per
	// first path segment (GroupPath), or all in one (GroupFlat).
	Group string
	// BaseURLVar is the variable prefixing every URL (default "base_url").
	BaseURLVar string
	Dialect    syntax.Dialect
}

GenerateOptions configure Generate.

type Generated

type Generated struct {
	Files []GeneratedFile
	// Variables are the values of the variables the files use: the base
	// URL (from the first server) and the path parameters (from their
	// examples), for a sonde.yaml environment.
	Variables map[string]string
	// Warnings, by kind, and the operations skipped with their reasons.
	Warnings []Note
	Skipped  []Note
}

Generated is the output of Generate.

type GeneratedFile

type GeneratedFile struct {
	// Path is relative, slash-separated, without extension.
	Path string
	File *syntax.File
}

GeneratedFile is the request file of one operation.

type LoadOptions

type LoadOptions struct {
	// AllowRemote allows an http(s) spec location and remote $ref
	// targets; without it both are errors.
	AllowRemote bool
	// HTTPClient fetches remote documents (nil: a client with a timeout).
	HTTPClient *http.Client
}

LoadOptions tell where a spec may be read from.

type Note

type Note struct{ Kind, Message string }

Note is a warning (Kind, Message) or a skipped operation (Kind: its name, Message: the reason).

type Options

type Options struct {
	// Server replaces the spec's servers for matching request URLs.
	Server string
	// Strict makes a request no operation matches a violation rather than
	// a warning.
	Strict bool
	// ExcludeOperations are never validated: "METHOD /path/template".
	ExcludeOperations []string
}

Options configure a validator.

type Route

type Route struct {
	// Template is the path as written in the spec ("/pets/{petId}").
	Template string
	// Params are the decoded values of the template's parameters.
	Params map[string]string
}

Route is a matched path template.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router matches request URLs to the path templates of a spec: the request path loses the longest matching server base path, then goes to the template matching it best (literal segments win over templated ones, from left to right, as OpenAPI requires).

func NewRouter

func NewRouter(templates, servers []string) *Router

NewRouter returns a router over templates, stripping the base path of each server URL (server variables replaced by their defaults) from request paths. Without servers the base path is "/".

func (*Router) Match

func (r *Router) Match(rawURL string, accept func(template string) bool) (Route, bool)

Match returns the route of rawURL's path among the templates accept takes (nil: all), and ok false when no server base path prefixes it or no such template matches.

type Spec

type Spec struct {
	// contains filtered or unexported fields
}

Spec is a loaded OpenAPI description. It is read only once loaded and shared by every validator of a run.

func Load

func Load(ctx context.Context, location string, opt LoadOptions) (*Spec, error)

Load reads the spec at location: a file path, or an http(s) URL with AllowRemote. A $ref may name another file inside the directory of a local spec, or, with AllowRemote, a remote document; Swagger 2.0 is converted to OpenAPI 3.

func (*Spec) ExampleResponse

func (s *Spec) ExampleResponse(method, rawURL string) (status int, header map[string]string, body any, contentType string, ok bool)

ExampleResponse returns an example response of the operation matching method and rawURL: the lowest documented 2xx status (or the first documented one), its required headers and an example body of its first media type. ok is false when no operation matches.

func (*Spec) Generate

func (s *Spec) Generate(opt GenerateOptions) (gen *Generated, err error)

Generate returns one request file per operation of the spec: path parameters as variables, required query parameters and headers with example values, security as variable placeholders, a body from the examples or the schema, and the lowest documented 2xx status as the expected response.

func (*Spec) Operations

func (s *Spec) Operations() []string

Operations returns the operations of the spec, "METHOD /path", sorted.

func (*Spec) Servers

func (s *Spec) Servers() []string

Servers returns the base URLs of the spec, variables replaced by their defaults.

func (*Spec) Validator

func (s *Spec) Validator(opt Options) *Validator

Validator returns a validator of the spec; validators share the loaded spec.

type Validator

type Validator struct {
	// contains filtered or unexported fields
}

Validator checks responses against a spec. It is safe for concurrent use.

func (*Validator) ValidateResponse

func (v *Validator) ValidateResponse(ctx context.Context, req *exchange.Request, resp *exchange.Response) (vs []engine.Violation)

ValidateResponse implements engine.ResponseValidator: it checks the status, the documented headers, the content type and, for JSON, the body. A HEAD request without its own operation is checked against GET, without its body.

Jump to

Keyboard shortcuts

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