Documentation
¶
Overview ¶
Package validator provides validation for OpenAPI Specification documents.
The validator supports OAS 2.0 through OAS 3.2.0, performing structural validation, format checking, and semantic analysis against the specification requirements. It includes best practice warnings and strict mode for enhanced validation.
Quick Start ¶
Validate a file with warnings enabled:
result, err := validator.Validate("openapi.yaml", true, false)
if err != nil {
log.Fatal(err)
}
if !result.Valid {
fmt.Printf("Found %d error(s)\n", result.ErrorCount)
}
Or create a reusable validator instance:
v := validator.New()
v.StrictMode = true
result, _ := v.Validate("api1.yaml")
result, _ := v.Validate("api2.yaml")
Features ¶
The validator checks document structure, required fields, format validation (URLs, emails, media types), semantic constraints (operation ID uniqueness, parameter consistency), and JSON schemas. Path validation includes checking for malformed templates (unclosed braces, reserved characters, consecutive slashes) and REST best practices (trailing slashes generate warnings when IncludeWarnings is enabled). See the examples in example_test.go for more usage patterns.
Validation Output ¶
ValidationResult contains:
- Valid: Boolean indicating if document is valid
- Version: Detected OpenAPI version (e.g., "3.0.3")
- Errors: Validation errors with JSON path locations
- Warnings: Best practice warnings (if IncludeWarnings is true)
- ErrorCount, WarningCount: Issue counts
See the exported ValidationError and ValidationResult types for complete details.
Index ¶
Examples ¶
Constants ¶
const ( // SeverityError indicates a spec violation that makes the document invalid SeverityError = severity.SeverityError // SeverityWarning indicates a best practice violation or recommendation SeverityWarning = severity.SeverityWarning )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ValidationError ¶
ValidationError represents a single validation issue
type ValidationResult ¶
type ValidationResult struct {
// Valid is true if no errors were found (warnings are allowed)
Valid bool
// Version is the detected OAS version string
Version string
// OASVersion is the enumerated OAS version
OASVersion parser.OASVersion
// Errors contains all validation errors
Errors []ValidationError
// Warnings contains all validation warnings
Warnings []ValidationError
// ErrorCount is the total number of errors
ErrorCount int
// WarningCount is the total number of warnings
WarningCount int
}
ValidationResult contains the results of validating an OpenAPI specification
func Validate ¶ added in v1.4.0
func Validate(specPath string, includeWarnings, strictMode bool) (*ValidationResult, error)
Validate is a convenience function that validates an OpenAPI specification file with the specified options. It's equivalent to creating a Validator with New(), setting the options, and calling Validate().
For one-off validation operations, this function provides a simpler API. For validating multiple files with the same configuration, create a Validator instance and reuse it.
Example:
result, err := validator.Validate("openapi.yaml", true, false)
if err != nil {
log.Fatal(err)
}
if !result.Valid {
// Handle validation errors
}
func ValidateParsed ¶ added in v1.4.0
func ValidateParsed(parseResult parser.ParseResult, includeWarnings, strictMode bool) (*ValidationResult, error)
ValidateParsed is a convenience function that validates an already-parsed OpenAPI specification with the specified options.
Example:
parseResult, _ := parser.Parse("openapi.yaml", false, true)
result, err := validator.ValidateParsed(*parseResult, true, false)
type Validator ¶
type Validator struct {
// IncludeWarnings determines whether to include best practice warnings
IncludeWarnings bool
// StrictMode enables stricter validation beyond the spec requirements
StrictMode bool
// UserAgent is the User-Agent string used when fetching URLs
// Defaults to "oastools" if not set
UserAgent string
}
Validator handles OpenAPI specification validation
func (*Validator) Validate ¶
func (v *Validator) Validate(specPath string) (*ValidationResult, error)
Validate validates an OpenAPI specification file
Example ¶
ExampleValidator_Validate demonstrates basic validation of an OpenAPI specification
package main
import (
"fmt"
"log"
"path/filepath"
"github.com/erraggy/oastools/validator"
)
func main() {
v := validator.New()
testFile := filepath.Join("testdata", "petstore-3.0.yaml")
result, err := v.Validate(testFile)
if err != nil {
log.Fatalf("Validation failed: %v", err)
}
fmt.Printf("Valid: %v\n", result.Valid)
fmt.Printf("Version: %s\n", result.Version)
fmt.Printf("Errors: %d\n", result.ErrorCount)
fmt.Printf("Warnings: %d\n", result.WarningCount)
}
Example (StrictMode) ¶
ExampleValidator_Validate_strictMode demonstrates validation with strict mode enabled
package main
import (
"fmt"
"log"
"path/filepath"
"github.com/erraggy/oastools/validator"
)
func main() {
v := validator.New()
v.StrictMode = true
testFile := filepath.Join("testdata", "petstore-3.0.yaml")
result, err := v.Validate(testFile)
if err != nil {
log.Fatalf("Validation failed: %v", err)
}
fmt.Printf("Valid: %v\n", result.Valid)
fmt.Printf("Errors: %d\n", result.ErrorCount)
fmt.Printf("Warnings: %d\n", result.WarningCount)
}
func (*Validator) ValidateParsed ¶ added in v1.3.1
func (v *Validator) ValidateParsed(parseResult parser.ParseResult) (*ValidationResult, error)
ValidateParsed validates an already parsed OpenAPI specification
Source Files