openapi

package
v1.5.0 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 2026 License: Apache-2.0 Imports: 28 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.

func Import added in v1.4.0

func Import(ctx context.Context, input string, opts ImportOptions) (convert.Output, error)

Import generates one file per operation of the spec at input (a path or a URL), and a sonde.yaml whose default environment sets the base URL and the path parameters.

func ResponseExample added in v1.2.0

func ResponseExample(ref *openapi3.SchemaRef) any

ResponseExample is Example for a response body: readOnly properties are kept and writeOnly ones left out.

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 ImportOptions added in v1.4.0

type ImportOptions struct {
	// Group lays files out by first tag (GroupTag), first path segment or
	// in one directory.
	Group string
	// BaseURLVar is the variable prefixing every URL.
	BaseURLVar string
	// AllowRemote allows a remote spec and remote $ref targets.
	AllowRemote bool
	Dialect     syntax.Dialect
	// Output is the directory the files go to: the spec is named as the
	// project's contract when it lies inside it.
	Output string
}

ImportOptions configure Import.

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 Mock added in v1.2.0

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

Mock answers requests with the documented responses of a spec (sonde mock). It keeps every kin-openapi type to itself, so the server around it only deals with net/http. It is read only and safe for concurrent use; its responses depend only on the request, never on earlier ones.

func (*Mock) Match added in v1.2.0

func (m *Mock) Match(method, path string) (*Operation, *Problem)

Match returns the operation of method on path, an escaped URL path: a 404 problem when no path template matches it, a 405 when its template has no such operation. A HEAD request falls back to the GET operation.

func (*Mock) Respond added in v1.2.0

func (m *Mock) Respond(o *Operation, sel Selection) (*Response, *Problem)

Respond renders the response sel chooses: its documented headers, the best media type for sel.Accept, and a body taken from the named or first example, else generated from the schema. The same operation and selection always give the same bytes.

func (*Mock) ValidateRequest added in v1.2.0

func (m *Mock) ValidateRequest(ctx context.Context, o *Operation, r *http.Request) (p *Problem)

ValidateRequest checks the parameters and the body of r, whose body must be readable again (the server reads it first, bounded), against the operation: nil when valid, a 415 problem for an undocumented content type, else a 422 listing the violations. Security requirements are not enforced.

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 Operation added in v1.2.0

type Operation struct {
	// Method is the operation's method: GET for a HEAD request answered
	// by the GET operation.
	Method   string
	Template string
	// Params are the decoded path parameters.
	Params map[string]string
	// contains filtered or unexported fields
}

Operation is the operation a request matched.

func (*Operation) Name added in v1.2.0

func (o *Operation) Name() string

Name is "METHOD /template".

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 Problem added in v1.2.0

type Problem struct {
	Status int
	Detail string
	// Violations list what is wrong with the request.
	Violations []string
	// Allow lists the methods of the path, for a 405.
	Allow []string
}

Problem is a request the mock refuses, answered with an RFC 9457 problem document.

func (*Problem) Error added in v1.2.0

func (p *Problem) Error() string

type Response added in v1.2.0

type Response struct {
	Status int
	Header http.Header
	Body   []byte
	// Warning is set when a body generated from the schema does not match
	// that schema (a schema the generator cannot satisfy).
	Warning string
}

Response is a mock response.

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 Selection added in v1.2.0

type Selection struct {
	// Status is a status code ("" for the lowest documented 2xx); it may
	// be documented exactly, by its range ("4XX") or by "default".
	Status string
	// Example names one of the media type's examples ("" for the first).
	Example string
	// Accept is the request's Accept header ("" accepts anything).
	Accept string
}

Selection chooses among the documented responses of an operation.

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) 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) Mock added in v1.2.0

func (s *Spec) Mock(server string) *Mock

Mock returns a mock of the spec. A non-empty server replaces the spec's servers: its base path is the one stripped from request paths.

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