Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsSwagger2 ¶
IsSwagger2 returns true when data appears to be a Swagger 2.0 (OAS2) spec. Scans only the first 1 KB to avoid parsing large files.
Types ¶
type CoveredOperation ¶
CoveredOperation identifies a spec operation (method + path pattern) exercised or missed.
func (CoveredOperation) String ¶
func (o CoveredOperation) String() string
type DiffChange ¶
type DiffChange struct {
// ID is the oasdiff rule identifier (e.g. "endpoint-removed").
ID string
// Text is a human-readable description of the change.
Text string
// Method is the HTTP method of the affected operation (may be empty for spec-level changes).
Method string
// Path is the URL path of the affected operation (may be empty for spec-level changes).
Path string
// Breaking is true when the change is not backward-compatible.
Breaking bool
// Level is ERR (breaking), WARN, or INFO.
Level string
}
DiffChange describes a single change between two spec versions.
func (DiffChange) Fails ¶
func (c DiffChange) Fails(on FailOn) bool
Fails reports whether this change makes a diff fail at the given threshold.
type DiffResult ¶
type DiffResult struct {
Changes []DiffChange
HasBreaking bool
}
DiffResult holds the full set of changes between two spec versions.
func Diff ¶
func Diff(base, revision *Spec) (*DiffResult, error)
Diff compares two already-parsed specs and classifies every change as breaking or non-breaking using oasdiff's default rule set.
func (*DiffResult) FailCount ¶
func (r *DiffResult) FailCount(on FailOn) int
FailCount is the number of changes that fail at the given threshold.
func (*DiffResult) Fails ¶
func (r *DiffResult) Fails(on FailOn) bool
Fails reports whether the diff fails at the given threshold. At the default threshold this is the same as HasBreaking.
type ExecutedRequest ¶
type ExecutedRequest struct {
Method string
URL string
StatusCode int // HTTP status code returned by the server
HadAuth bool // whether the request carried any auth credentials
Passed bool // whether this step's assertions all passed
}
ExecutedRequest is a (method, full URL) pair from an executed scenario step.
type ExercisedResult ¶
type ExercisedResult struct {
CoveredOperation
Passed bool
StatusCodes []int // all unique status codes observed across matching executions
HadAuth bool // whether at least one execution carried auth credentials
}
ExercisedResult pairs a matched spec operation with the last-run pass/fail outcome.
type FailOn ¶
type FailOn string
FailOn is how serious a spec change must be before a diff counts as failed.
const ( // FailOnBreaking fails only on breaking changes (level ERR). This is the default. FailOnBreaking FailOn = "breaking" // FailOnWarning also fails on potentially breaking changes (level WARN). FailOnWarning FailOn = "warning" // FailOnInfo fails on any change at all, including informational ones. FailOnInfo FailOn = "info" )
func ParseFailOn ¶
ParseFailOn reads a --fail-on value; the empty string means the default.
type GeneratedRequest ¶
type GeneratedRequest struct {
Request *domain.Request
OperationID string
Summary string
Tags []string
Path string // raw path from the spec, e.g. "/user/{username}"
}
GeneratedRequest is a domain.Request augmented with metadata from the spec.
func GenerateRequests ¶
func GenerateRequests(s *Spec, baseURL string) ([]GeneratedRequest, error)
GenerateRequests creates one domain.Request per operation in the spec. baseURL overrides the first server URL when non-empty.
func ParseSwagger2Bytes ¶
func ParseSwagger2Bytes(data []byte, format, baseURL string) (title, version string, reqs []GeneratedRequest, err error)
ParseSwagger2Bytes parses a Swagger 2.0 spec and generates request stubs directly, bypassing kin-openapi which only supports OpenAPI 3.x. If baseURL is non-empty it overrides the spec's host+basePath+schemes.
type NegativeProbe ¶
type NegativeProbe struct {
Request *domain.Request
OperationID string
Method string
Path string
Kind ProbeKind
Description string
}
NegativeProbe is a request intentionally crafted to violate the spec, paired with metadata describing which contract rule it exercises.
func GenerateNegativeProbes ¶
func GenerateNegativeProbes(s *Spec, baseURL string) ([]NegativeProbe, error)
GenerateNegativeProbes creates probes for every operation that declares a request body, security requirement, or required query parameters. Each probe is a request that should be rejected by a spec-compliant server.
type ProbeKind ¶
type ProbeKind string
ProbeKind classifies the contract rule a negative probe exercises.
type ScenarioCoverageResult ¶
type ScenarioCoverageResult struct {
Covered int
Total int
Percent float64
Exercised []CoveredOperation
Missed []CoveredOperation
ExercisedResults []ExercisedResult // per-operation last pass/fail outcome
}
ScenarioCoverageResult is the coverage computed from matching executed requests against an OpenAPI spec's declared operations.
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec wraps a loaded OpenAPI document.
func ParseBytes ¶
ParseBytes parses an OpenAPI 3.0 or 3.1 spec from raw bytes. format must be "yaml", "yml", or "json".
func (*Spec) AllOperations ¶
func (s *Spec) AllOperations() []CoveredOperation
AllOperations returns every operation declared in the spec as (METHOD, path) pairs, sorted by path then method.
func (*Spec) ScenarioCoverage ¶
func (s *Spec) ScenarioCoverage(executed []ExecutedRequest) *ScenarioCoverageResult
ScenarioCoverage matches each executed request against the spec's declared operations and returns a coverage summary.
type SpecMeta ¶
type SpecMeta struct {
// DeclaredStatusCodes maps "METHOD /path" → all HTTP status codes declared
// in the spec's responses object for that operation.
DeclaredStatusCodes map[string][]int
// SecuredOps is the set of "METHOD /path" strings for operations that
// declare at least one security requirement.
SecuredOps map[string]bool
}
SpecMeta contains the parts of a spec needed for coverage quality computation.
func ExtractSpecMeta ¶
ExtractSpecMeta extracts quality-relevant metadata from a loaded spec.
type ValidationError ¶
ValidationError is a single schema violation.
func ValidateRequest ¶
func ValidateRequest(s *Spec, req *domain.Request) []ValidationError
ValidateRequest checks that req conforms to the spec's declared request schema for the matching operation. Returns nil if valid or if the path is not in the spec.
func ValidateResponse ¶
func ValidateResponse(s *Spec, operationID string, resp *domain.Response) []ValidationError
ValidateResponse checks that resp conforms to the declared response schema for the given operationID and HTTP status code. Returns nil if valid, a list of violations otherwise.
func ValidateResponseByPath ¶
func ValidateResponseByPath(s *Spec, method, path string, statusCode int, resp *domain.Response) []ValidationError
ValidateResponseByPath validates a response against the spec using the HTTP method and path directly, without needing an operationID.
func (ValidationError) Error ¶
func (e ValidationError) Error() string