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
- func Import(ctx context.Context, input string, opts ImportOptions) (convert.Output, error)
- func ResponseExample(ref *openapi3.SchemaRef) any
- type GenerateOptions
- type Generated
- type GeneratedFile
- type ImportOptions
- type LoadOptions
- type Mock
- type Note
- type Operation
- type Options
- type Problem
- type Response
- type Route
- type Router
- type Selection
- type Spec
- 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.
func Import ¶ added in v1.4.0
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
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
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
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
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.
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.
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).
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 ¶
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
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 ¶
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.