openapi

package
v0.0.0-...-6ea40c6 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsSwagger2

func IsSwagger2(data []byte) bool

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

type CoveredOperation struct {
	Method string
	Path   string
}

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

func ParseFailOn(s string) (FailOn, error)

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.

const (
	ProbeDropRequiredField    ProbeKind = "drop_required_field"
	ProbeWrongFieldType       ProbeKind = "wrong_field_type"
	ProbeMissingRequiredParam ProbeKind = "missing_required_param"
	ProbeMissingAuth          ProbeKind = "missing_auth"
)

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

func ParseBytes(data []byte, format string) (*Spec, error)

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) Info

func (s *Spec) Info() (title, version string)

Info returns the spec title and version.

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

func ExtractSpecMeta(s *Spec) SpecMeta

ExtractSpecMeta extracts quality-relevant metadata from a loaded spec.

type ValidationError

type ValidationError struct {
	Path    string
	Message string
}

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

Jump to

Keyboard shortcuts

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