validator

Example_customValidation demonstrates how to use the validator with custom options for best practice warnings and strict validation.

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/erraggy/oastools/validator"
)

func main() {
	// Create a validator with strict mode and warnings enabled
	v := validator.New()
	v.IncludeWarnings = true // Include best-practice warnings
	v.StrictMode = true      // Enforce strict validation rules

	// Validate an OpenAPI specification
	testFile := filepath.Join("testdata", "petstore-3.0.yaml")
	result, err := v.Validate(testFile)
	if err != nil {
		log.Fatal(err)
	}

	// Separate errors from warnings by severity
	errors := 0
	warnings := 0

	for _, issue := range result.Errors {
		// Severity levels: SeverityCritical=3, SeverityError=2, SeverityWarning=1, SeverityInfo=0
		switch issue.Severity {
		case validator.SeverityCritical:
			errors++ // Critical issues are also errors
			fmt.Printf("CRITICAL [%s]: %s\n", issue.Path, issue.Message)
		case validator.SeverityError:
			errors++
			fmt.Printf("ERROR [%s]: %s\n", issue.Path, issue.Message)
		case validator.SeverityWarning:
			warnings++
			fmt.Printf("WARNING [%s]: %s\n", issue.Path, issue.Message)
		case validator.SeverityInfo:
			fmt.Printf("INFO [%s]: %s\n", issue.Path, issue.Message)
		}
	}

	// Summary
	fmt.Printf("\nValidation complete:\n")
	fmt.Printf("- Valid: %v\n", result.Valid)
	fmt.Printf("- Errors: %d\n", errors)
	fmt.Printf("- Warnings: %d\n", warnings)

	// StrictMode treats warnings as errors for result.Valid
	// IncludeWarnings populates result.Errors with warning-level issues
}

Example_operationContext demonstrates how validation errors include operation context to help identify which API operation an error relates to. This is especially useful for errors in shared components (schemas, responses) that are referenced by multiple operations.

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/parser"
	"github.com/erraggy/oastools/validator"
)

func main() {
	// A spec with a validation error in an operation
	spec := `
openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      operationId: getUser
      parameters:
        - name: wrongName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
`
	parseResult, err := parser.ParseWithOptions(parser.WithBytes([]byte(spec)))
	if err != nil {
		log.Fatal(err)
	}

	result, err := validator.ValidateWithOptions(
		validator.WithParsed(*parseResult),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Validation errors include operation context
	for _, e := range result.Errors {
		// The String() method includes operation context automatically
		fmt.Println(e.String())

		// You can also access the OperationContext programmatically
		if e.OperationContext != nil {
			fmt.Printf("  Operation: %s %s\n", e.OperationContext.Method, e.OperationContext.Path)
			if e.OperationContext.OperationID != "" {
				fmt.Printf("  OperationId: %s\n", e.OperationContext.OperationID)
			}
		}
	}

}

Output:

✗ paths./users/{userId}.get (operationId: getUser): Path template references parameter '{userId}' but it is not declared in parameters
    Spec: https://spec.openapis.org/oas/v3.0.0.html#path-item-object
  Operation: GET /users/{userId}
  OperationId: getUser

Example_toParseResult demonstrates using ToParseResult for package chaining. This pattern allows validated documents to be passed to other oastools packages.

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/erraggy/oastools/validator"
)

func main() {
	// Validate a specification
	v := validator.New()
	testFile := filepath.Join("testdata", "petstore-3.0.yaml")
	result, err := v.Validate(testFile)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Valid: %v\n", result.Valid)

	// Convert to ParseResult for use with other packages
	parseResult := result.ToParseResult()
	fmt.Printf("SourcePath: %s\n", parseResult.SourcePath)
	fmt.Printf("Version: %s\n", parseResult.Version)

	// The ParseResult can now be passed to fixer, converter, joiner, etc.
	// For example:
	//   fixResult, _ := fixer.FixWithOptions(fixer.WithParsed(*parseResult))
	//   convertResult, _ := converter.ConvertWithOptions(converter.WithParsed(*parseResult), ...)
}