openapi3lint

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

• func RulesConfigExample1() map[string]RuleConfig
• func StandardRuleNames() []string
• func ValidateRules(rules map[string]Rule) error
• type EmptyRule
  • func (rule EmptyRule) Name() string
  • func (rule EmptyRule) ProcessOperation(spec *oas3.Swagger, op *oas3.Operation, opPointer, path, method string) []lintutil.PolicyViolation
  • func (rule EmptyRule) ProcessSpec(spec *oas3.Swagger, pointerBase string) []lintutil.PolicyViolation
  • func (rule EmptyRule) Scope() string
  • func (rule EmptyRule) Severity() string
• type Policy
  • func (pol *Policy) AddRule(rule Rule, errorOnCollision bool) error
  • func (pol *Policy) RuleNames() []string
  • func (pol *Policy) ValidateSpec(spec *oas3.Swagger, pointerBase, filterSeverity string) (*lintutil.PolicyViolationsSets, error)
• type PolicyConfig
  • func NewPolicyConfigFile(filename string) (PolicyConfig, error)
  • func (cfg *PolicyConfig) StandardPolicy() (Policy, error)
• type Rule
  • func NewStandardRule(name, sev string) (Rule, error)
• type RuleConfig
• type RulesMap

Functions

func RulesConfigExample1

func RulesConfigExample1() map[string]RuleConfig

func StandardRuleNames

func StandardRuleNames() []string

func ValidateRules

func ValidateRules(rules map[string]Rule) error

Types

type EmptyRule

type EmptyRule struct{}

func (EmptyRule) Name

func (rule EmptyRule) Name() string

func (EmptyRule) ProcessOperation

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

func (EmptyRule) ProcessSpec

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

func (EmptyRule) Scope

func (rule EmptyRule) Scope() string

func (EmptyRule) Severity

func (rule EmptyRule) Severity() string

type Policy

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

func (*Policy) AddRule

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

func (*Policy) RuleNames

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

func (*Policy) ValidateSpec

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

type PolicyConfig

type PolicyConfig struct {
	Rules map[string]RuleConfig `json:"rules,omitempty"`
}

func NewPolicyConfigFile

func NewPolicyConfigFile(filename string) (PolicyConfig, error)

func (*PolicyConfig) StandardPolicy

func (cfg *PolicyConfig) StandardPolicy() (Policy, error)

type Rule

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

func NewStandardRule

func NewStandardRule(name, sev string) (Rule, error)

type RuleConfig

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

type RulesMap

type RulesMap map[string]Rule