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
- func Example(ref *openapi3.SchemaRef) any
- type GenerateOptions
- type Generated
- type GeneratedFile
- type LoadOptions
- type Note
- type Options
- type Route
- type Router
- type Spec
- func (s *Spec) ExampleResponse(method, rawURL string) (status int, header map[string]string, body any, contentType string, ok bool)
- func (s *Spec) Generate(opt GenerateOptions) (gen *Generated, err error)
- func (s *Spec) Operations() []string
- func (s *Spec) Servers() []string
- func (s *Spec) Validator(opt Options) *Validator
- type Validator
Constants ¶
const ( GroupTag = "tag" GroupPath = "path" GroupFlat = "flat" )
Grouping values of GenerateOptions.Group.
const MaxSpecBytes = 64 << 20
MaxSpecBytes caps a spec file and each file it references.
Variables ¶
This section is empty.
Functions ¶
func Example ¶
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).
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 ¶
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 ¶
Operations returns the operations of the spec, "METHOD /path", sorted.
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.