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 using functional options:
result, err := validator.ValidateWithOptions(
validator.WithFilePath("openapi.yaml"),
validator.WithIncludeWarnings(true),
)
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 Option ¶ added in v1.11.0
type Option func(*validateConfig) error
Option is a function that configures a validation operation
func WithFilePath ¶ added in v1.11.0
WithFilePath specifies a file path or URL as the input source
func WithIncludeWarnings ¶ added in v1.11.0
WithIncludeWarnings enables or disables best practice warnings Default: true
func WithParsed ¶ added in v1.11.0
func WithParsed(result parser.ParseResult) Option
WithParsed specifies a parsed ParseResult as the input source
func WithStrictMode ¶ added in v1.11.0
WithStrictMode enables or disables strict validation beyond spec requirements Default: false
func WithUserAgent ¶ added in v1.11.0
WithUserAgent sets the User-Agent string for HTTP requests Default: "" (uses parser default)
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
// LoadTime is the time taken to load the source data
LoadTime time.Duration
// SourceSize is the size of the source data in bytes
SourceSize int64
// Stats contains statistical information about the document
Stats parser.DocumentStats
}
ValidationResult contains the results of validating an OpenAPI specification
func Validate
deprecated
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.
Deprecated: Use ValidateWithOptions for a more flexible API.
Example:
result, err := validator.Validate("openapi.yaml", true, false)
if err != nil {
log.Fatal(err)
}
if !result.Valid {
// Handle validation errors
}
func ValidateParsed
deprecated
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.
Deprecated: Use ValidateWithOptions for a more flexible API.
Example:
parseResult, _ := parser.Parse("openapi.yaml", false, true)
result, err := validator.ValidateParsed(*parseResult, true, false)
func ValidateWithOptions ¶ added in v1.11.0
func ValidateWithOptions(opts ...Option) (*ValidationResult, error)
ValidateWithOptions validates an OpenAPI specification using functional options. This provides a flexible, extensible API that combines input source selection and configuration in a single function call.
Example:
result, err := validator.ValidateWithOptions(
validator.WithFilePath("openapi.yaml"),
validator.WithStrictMode(true),
)
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