openapi3lint

package
v1.18.5 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2024 License: MIT Imports: 26 Imported by: 0

README

OpenAPI 3 Lint

This is a Go-based OpenAPI 3 spec linter.

Spectrum is designed to support a multi-file, multi-user, async editing process where linting reports need to be resilinent to mutiple changes to the specs occurring between the time the validation is run and resolved.

Why Spectrum Linter?

There are a few linters available.

The reasons this exists are:

  1. written in Go so its easy to use/modify for Go devs
  2. policy violations are grouped by rule, vs. line number for easier mitigation
  3. policy violations are identified by JSON Schema pointere vs. line number for easier identification when using merged files

Standard Rules

The following rules are built into Spectrum.

  1. datatype-int-format-standard-exist: ensures data types of integer have a standard format (int32 or int64)
  2. operation-operationid-style-camelcase: ensures operationIds use camelCase
  3. operation-operationid-style-kebabcase: ensures operationIds use kebab-case
  4. operation-operationid-style-pascalcase: ensures operationIds use PascalCase
  5. operation-operationid-style-snakecase: ensures operationIds use snake_case
  6. operation-summary-exist ensures a summary exists.
  7. operation-summary-style-first-uppercase: ensures summary starts with capitalized first character
  8. path-param-style-camelcase: path parms are camel case
  9. path-param-style-kebabcase: path parms are kebab case
  10. path-param-style-pascalcase: path parms are Pascal case
  11. path-param-style-snakecase: path parms are snake case
  12. schema-has-reference: ensures schemas have references
  13. schema-object-properties-exist: schema of type object have properties or additionalProperties defined
  14. schema-property-enum-style-camelcase: schema property enums are camel case
  15. schema-property-enum-style-kebabcase: schema property enums are kebab case
  16. schema-property-enum-style-pascalcase: schema property enums are Pascal case
  17. schema-property-enum-style-snakecase: schema property enums are snake case
  18. schema-reference-has-schema: ensures schma JSON pointers reference existing schemas
  19. tag-style-first-uppercase: Tag names have capitalized first character

Other Linters

There are other linters available. To date, Spectrum Linter hasn't beeen inspired by any of them, though there is a desire and effort to align on rule names and potentially rule definitions to achieve similar behavior.

  1. Mermade OAS-Kit - https://github.com/mermade/oas-kit
    1. https://mermade.github.io/oas-kit/default-rules.html
    2. https://mermade.github.io/oas-kit/linter-rules.html
  2. Spectral - https://github.com/stoplightio/spectral
    1. Inspired by Speccy
  3. Speccy - https://github.com/wework/speccy
    1. Inspired by OAS-Kit

Documentation

Index

Constants

View Source 
const (
	RuleTypeAll        = "all"
	RuleTypeStandard   = "standard"
	RuleTypeXDefined   = "xdefined"
	RuleTypeXUndefined = "xundefined"
)

Variables

View Source 
var ErrNoSpecFiles = errors.New("no spec files supplied")

Functions

func RulesConfigExample1 added in v1.7.0 

func RulesConfigExample1() map[string]RuleConfig

func ValidateRules 

func ValidateRules(policyRules map[string]PolicyRule) error

Types

type EmptyRule added in v1.7.0 

type EmptyRule struct{}

func (EmptyRule) Name added in v1.7.0 

func (rule EmptyRule) Name() string

func (EmptyRule) ProcessOperation added in v1.7.0 

func (rule EmptyRule) ProcessOperation(spec *openapi3.Spec, op *oas3.Operation, opPointer, path, method string) []lintutil.PolicyViolation

func (EmptyRule) ProcessSpec added in v1.7.0 

func (rule EmptyRule) ProcessSpec(spec *openapi3.Spec, pointerBase string) []lintutil.PolicyViolation

func (EmptyRule) Scope added in v1.7.0 

func (rule EmptyRule) Scope() string

type Policy 

type Policy struct {
	// contains filtered or unexported fields
}

func NewPolicy added in v1.8.0 

func NewPolicy() Policy

func NewPolicyWithConfig added in v1.14.0 

func NewPolicyWithConfig(policyfile string) (Policy, error)

NewPolicyWithConfig is useful when not programatically augmenting the `PolicyConfig` struct before creating the `Policy` struct. For example, `PolicyConfig.AddRuleCollection()` can be called programmtcally. before calling `PolicyConfig.Policy()`.

func (*Policy) AddRule 

func (pol *Policy) AddRule(rule Rule, sev string, errorOnCollision bool) error

func (*Policy) RuleNames 

func (pol *Policy) RuleNames() []string

func (*Policy) ValidateSpec 

func (pol *Policy) ValidateSpec(spec *openapi3.Spec, pointerBase, filterSeverity string) (*lintutil.PolicyViolationsSets, error)

func (*Policy) ValidateSpecFiles added in v1.14.0 

func (pol *Policy) ValidateSpecFiles(filterSeverity string, specfiles []string) (*lintutil.PolicyViolationsSets, error)

ValidateSpecFiles executes the policy against a set of one or more spec files. `sev` is the severity as specified by `github.com/grokify/mogo/log/severity`. A benefit of using this over `ValidateSpec()` when validating multiple files is that this will automatically inject the filename as a JSON pointer base.`

type PolicyConfig 

type PolicyConfig struct {
	Name                 string                `json:"name"`
	Version              string                `json:"version"`
	LastUpdated          time.Time             `json:"lastUpdated,omitempty"`
	IncludeStandardRules bool                  `json:"includeStandardRules"`
	Rules                map[string]RuleConfig `json:"rules,omitempty"`
	NonStandardRules     []string              `json:"nonStandardRules,omitempty"`
	// contains filtered or unexported fields
}

func NewPolicyConfigFile 

func NewPolicyConfigFile(filename string) (PolicyConfig, error)

func (*PolicyConfig) AddRuleCollection added in v1.7.3 

func (polCfg *PolicyConfig) AddRuleCollection(collection RuleCollection)

func (*PolicyConfig) Policy added in v1.7.3 

func (polCfg *PolicyConfig) Policy() (Policy, error)

func (*PolicyConfig) RuleNames added in v1.7.1 

func (polCfg *PolicyConfig) RuleNames() map[string][]string

type PolicyRule added in v1.8.0 

type PolicyRule struct {
	Rule     Rule
	Severity string
}

type Rule 

type Rule interface {
	Name() string
	Scope() string
	ProcessSpec(spec *openapi3.Spec, pointerBase string) []lintutil.PolicyViolation
	ProcessOperation(spec *openapi3.Spec, op *oas3.Operation, opPointer, path, method string) []lintutil.PolicyViolation
}

type RuleCollection added in v1.7.3 

type RuleCollection interface {
	Name() string
	RuleNames() []string
	RuleExists(ruleName string) bool
	Rule(ruleName string) (Rule, error)
}

type RuleCollectionSimple added in v1.8.0 

type RuleCollectionSimple struct {
	// contains filtered or unexported fields
}

func (RuleCollectionSimple) AddRule added in v1.8.0 

func (simple RuleCollectionSimple) AddRule(rule Rule) error

func (RuleCollectionSimple) Name added in v1.8.0 

func (simple RuleCollectionSimple) Name() string

func (RuleCollectionSimple) Rule added in v1.8.0 

func (simple RuleCollectionSimple) Rule(ruleName string) (Rule, error)

func (RuleCollectionSimple) RuleExists added in v1.8.0 

func (simple RuleCollectionSimple) RuleExists(ruleName string) bool

func (RuleCollectionSimple) RuleNames added in v1.8.0 

func (simple RuleCollectionSimple) RuleNames() []string

type RuleCollectionStandard added in v1.7.3 

type RuleCollectionStandard struct {
	// contains filtered or unexported fields
}

func NewRuleCollectionStandard added in v1.7.3 

func NewRuleCollectionStandard() RuleCollectionStandard

func (RuleCollectionStandard) Name added in v1.7.3 

func (std RuleCollectionStandard) Name() string

func (RuleCollectionStandard) Rule added in v1.7.3 

func (std RuleCollectionStandard) Rule(name string) (Rule, error)

func (RuleCollectionStandard) RuleExists added in v1.7.3 

func (std RuleCollectionStandard) RuleExists(ruleName string) bool

func (RuleCollectionStandard) RuleNames added in v1.7.3 

func (std RuleCollectionStandard) RuleNames() []string

type RuleCollections added in v1.7.3 

type RuleCollections []RuleCollection

type RuleConfig 

type RuleConfig struct {
	Severity string `json:"severity"`
}

type RulesMap 

type RulesMap map[string]Rule

Source Files

View all Source files

Directories

Path Synopsis
ruletaggroupexist
ruleschemaobjectpropsexist ensures that schema objects have properties.
 ruleschemaobjectpropsexist ensures that schema objects have properties.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.