config

Documentation

Index

• Constants
• func Save(w io.Writer, proj *Project) error
• type API
• type APIs
• type Generator
• type GeneratorScope
• type Generators
  • func LoadGenerators(r io.Reader) (Generators, error)
• type Linter
• type Linters
• type OpticCILinter
• type Output
  • func (o *Output) ResolvePaths() []string
• type Overlay
• type Project
  • func Load(r io.Reader) (*Project, error)
  • func (p *Project) APINames() []string
• type ResourceSet
• type SpectralLinter

Constants

const (
	// GeneratorScopeDefault indicates the default scope should be used in
	// configuration.
	GeneratorScopeDefault = ""

	// GeneratorScopeVersion indicates the generator operates on a single
	// resource version.
	GeneratorScopeVersion = "version"

	// GeneratorScopeResource indicates the generator operates on all versions
	// in a resource. This is useful for generating version routers, for
	// example.
	GeneratorScopeResource = "resource"
)

Functions

func Save

func Save(w io.Writer, proj *Project) error

Save saves a Project configuration to YAML.

Types

type API

type API struct {
	Name      string         `json:"-"`
	Resources []*ResourceSet `json:"resources"`
	Overlays  []*Overlay     `json:"overlays"`
	Output    *Output        `json:"output"`
}

An API defines how and where to build versioned OpenAPI documents from a source collection of individual resource specifications and additional overlay content to merge.

type APIs

type APIs map[string]*API

APIs defines a named map of API instances.

type Generator

type Generator struct {
	Name      string         `json:"-"`
	Scope     GeneratorScope `json:"scope"`
	Filename  string         `json:"filename,omitempty"`
	Template  string         `json:"template"`
	Files     string         `json:"files,omitempty"`
	Functions string         `json:"functions,omitempty"`
}

Generator describes how files are generated for a resource.

type GeneratorScope

type GeneratorScope string

GeneratorScope determines the template context when running the generator. Different scopes allow templates to operate over a single resource version, or all versions in a resource, for example.

type Generators

type Generators map[string]*Generator

Generators defines a named map of Generator instances.

func LoadGenerators

func LoadGenerators(r io.Reader) (Generators, error)

LoadGenerators loads Generators from their YAML representation.

type Linter

type Linter struct {
	Name        string          `json:"-"`
	Description string          `json:"description,omitempty"`
	Spectral    *SpectralLinter `json:"spectral"`
	SweaterComb *OpticCILinter  `json:"sweater-comb"`
	OpticCI     *OpticCILinter  `json:"optic-ci"`
}

Linter describes a set of standards and rules that an API should satisfy. NOTE: Linters are deprecated and may be removed in v5.

type Linters

type Linters map[string]*Linter

Linters defines a named map of Linter instances. NOTE: Linters are deprecated and may be removed in v5.

type OpticCILinter

type OpticCILinter struct {
	// Image identifies the Optic CI docker image to use for linting.
	Image string

	// Script identifies the path to the Optic CI script to use for linting.
	// Mutually exclusive with Image; if Script is specified Docker will not be
	// used.
	Script string

	// Original is where to source the original version of an OpenAPI spec file
	// when comparing. If empty, all changes are assumed to be new additions.
	Original string `json:"original,omitempty"`

	// Proposed is where to source the proposed changed version of an OpenAPI
	// spec file when comparing. If empty, this is assumed to be the
	// local working copy.
	Proposed string `json:"proposed,omitempty"`

	// Debug turns on debug logging.
	Debug bool `json:"debug,omitempty"`

	// Deprecated: CIContext is no longer used and should be removed in the
	// next major release.
	CIContext string `json:"-"`

	// Deprecated: UploadResults is no longer used and should be removed in the
	// next major release. Uploading optic-ci comparison results to Optic
	// Cloud is determined by the presence of environment variables.
	UploadResults bool `json:"-"`

	// Exceptions are files that are excluded from CI checks. This is an escape
	// hatch of last resort, if a file needs to land and can't pass CI yet.
	// They are specified as a mapping from project relative path to sha256
	// sums of that spec file that is exempt. This makes the exception very
	// narrow -- only a specific version of a specific file is skipped, after
	// outside review and approval.
	Exceptions map[string][]string

	// ExtraArgs may be used to pass extra arguments to `optic-ci`.
	ExtraArgs []string `json:"extraArgs"`
}

OpticCILinter identifies an Optic CI Linter, which is distributed as a self-contained docker image. NOTE: Linters are deprecated and may be removed in v5.

type Output

type Output struct {
	Path   string   `json:"path,omitempty"`
	Paths  []string `json:"paths,omitempty"`
	Linter string   `json:"linter"`
}

Output defines where the aggregate versioned OpenAPI specs should be created during compilation.

func (*Output) ResolvePaths

func (o *Output) ResolvePaths() []string

EffectivePaths returns a slice of effective configured output paths, whether a single or multiple output paths have been configured.

type Overlay

type Overlay struct {
	Include string `json:"include"`
	Inline  string `json:"inline"`
}

An Overlay defines additional OpenAPI documents to merge into the aggregate OpenAPI spec when compiling an API. These might include special endpoints that should be included in the aggregate API but are not versioned, or top-level descriptions of the API itself.

type Project

type Project struct {
	Version string `json:"version"`
	// NOTE: Linters are deprecated and may be removed in v5.
	Linters    Linters    `json:"linters,omitempty"`
	Generators Generators `json:"generators,omitempty"`
	APIs       APIs       `json:"apis"`
}

Project defines collection of APIs and the standards they adhere to.

func Load

func Load(r io.Reader) (*Project, error)

Load loads a Project configuration from its YAML representation.

func (*Project) APINames

func (p *Project) APINames() []string

APINames returns the API names in deterministic ascending order.

type ResourceSet

type ResourceSet struct {
	Description     string             `json:"description"`
	Linter          string             `json:"linter"`
	LinterOverrides map[string]Linters `json:"linter-overrides"`
	Path            string             `json:"path"`
	Excludes        []string           `json:"excludes"`
}

A ResourceSet defines a set of versioned resources that adhere to the same standards.

Versioned resources are expressed as individual OpenAPI documents in a directory structure:

+-resource

|
+-2021-08-01
| |
| +-spec.yaml
| +-<implementation code, etc. can go here>
|
+-2021-08-15
| |
| +-spec.yaml
| +-<implementation code, etc. can go here>
...

Each YYYY-mm-dd directory under a resource is a version. The spec.yaml in each version is a complete OpenAPI document describing the resource at that version.

type SpectralLinter

type SpectralLinter struct {

	// Rules are a list of Spectral ruleset file locations
	Rules []string `json:"rules"`

	// Script identifies the path to the spectral script to use for linting.
	// If not defined linting will look for spectral-cli on $PATH.
	Script string `json:"script"`

	// ExtraArgs may be used to pass extra arguments to `spectral lint`. If not
	// specified, the default arguments `--format text` are used when running
	// spectral. The `-r` flag must not be specified here, as this argument is
	// automatically added from the Rules setting above.
	//
	// See https://meta.stoplight.io/docs/spectral/ZG9jOjI1MTg1-spectral-cli
	// for the options supported.
	ExtraArgs []string `json:"extraArgs"`
}

SpectralLinter identifies a Linter as a collection of Spectral rulesets. NOTE: Linters are deprecated and may be removed in v5.