Documentation ¶
Overview ¶
Package vervet supports opinionated API versioning tools.
Index ¶
- Constants
- Variables
- func ComponentsEqual(x, y interface{}) bool
- func ExtensionString(extensions map[string]interface{}, key string) (string, error)
- func IncludeHeaders(doc *Document) error
- func IsExtensionNotFound(err error) bool
- func LoadVersions(root fs.FS) ([]*openapi3.T, error)
- func Localize(ctx context.Context, doc *Document) error
- func Merge(dst, src *openapi3.T, replace bool) error
- func RemoveElements(doc *openapi3.T, excludes ExcludePatterns) error
- func RemoveRefs(target interface{}) error
- func ResolveRefsWithoutSourceName(t *openapi3.T, componentRef openapi3.ComponentRef) string
- func ToSpecJSON(v interface{}) ([]byte, error)
- func ToSpecYAML(v interface{}) ([]byte, error)
- func VersionDateStrings(vs []Version) []string
- func WithGeneratedComment(yamlBuf []byte) ([]byte, error)
- type Collator
- type CollatorOption
- type Document
- func (d *Document) Lifecycle() (Lifecycle, error)
- func (d *Document) LoadReference(relPath, refPath string, target interface{}) (_ string, returnErr error)
- func (d *Document) Location() *url.URL
- func (d *Document) MarshalJSON() ([]byte, error)
- func (d *Document) RelativePath() string
- func (d *Document) ResolveRefs() error
- func (d *Document) Version() (Version, error)
- type ExcludePatterns
- type Inliner
- func (in *Inliner) AddRef(ref string)
- func (in *Inliner) Inline(doc *openapi3.T) error
- func (in *Inliner) ProcessCallbackRef(ref *openapi3.CallbackRef) error
- func (in *Inliner) ProcessExampleRef(ref *openapi3.ExampleRef) error
- func (in *Inliner) ProcessHeaderRef(ref *openapi3.HeaderRef) error
- func (in *Inliner) ProcessLinkRef(ref *openapi3.LinkRef) error
- func (in *Inliner) ProcessParameterRef(ref *openapi3.ParameterRef) error
- func (in *Inliner) ProcessRequestBodyRef(ref *openapi3.RequestBodyRef) error
- func (in *Inliner) ProcessResponseRef(ref *openapi3.ResponseRef) error
- func (in *Inliner) ProcessSchemaRef(ref *openapi3.SchemaRef) error
- func (in *Inliner) ProcessSecuritySchemeRef(ref *openapi3.SecuritySchemeRef) error
- type Lifecycle
- type RefIndex
- type ResourceVersion
- type ResourceVersions
- type SpecVersions
- type Stability
- type Version
- func (v Version) AddDays(days int) Version
- func (v Version) Compare(vr Version) int
- func (v Version) DateString() string
- func (v Version) DeprecatedBy(vr Version) bool
- func (v *Version) LifecycleAt(t time.Time) Lifecycle
- func (v Version) String() string
- func (v Version) Sunset(vr Version) (time.Time, bool)
- type VersionIndex
- func (vi *VersionIndex) Deprecates(q Version) (Version, bool)
- func (vi *VersionIndex) Resolve(query Version) (Version, error)
- func (vi *VersionIndex) ResolveForBuild(query Version) (Version, error)
- func (vi *VersionIndex) ResolveGAorBetaStability(query Version) (Version, error)
- func (vi *VersionIndex) Versions() VersionSlice
- type VersionSlice
Constants ¶
const ( // ExtSnykApiStability is used to annotate a top-level resource version // spec with its API release stability level. ExtSnykApiStability = "x-snyk-api-stability" // ExtApiStability is used to annotate a path in a compiled OpenAPI spec // with its API release stability level. ExtApiStabilityLevel = "x-stability-level" // ExtSnykApiLifecycle is used to annotate compiled OpenAPI with lifecycle // stage: releases, deprecated or sunset. It is applied at the top-level as // well as per-operation. ExtSnykApiLifecycle = "x-snyk-api-lifecycle" // ExtSnykApiResource is used to annotate a path in a compiled OpenAPI spec // with its source resource name. ExtSnykApiResource = "x-snyk-api-resource" // ExtSnykApiVersion is used to annotate a path in a compiled OpenAPI spec // with its resolved release version. It is also used to identify the // overall version of the compiled spec at the document level. ExtSnykApiVersion = "x-snyk-api-version" // ExtSnykApiOwner is used to annotate an operation in a compiled OpenAPI spec // with the owners of the operation. This is useful to get to the owning github team. ExtSnykApiOwner = "x-snyk-api-owners" // ExtSnykApiReleases is used to annotate a path in a compiled OpenAPI spec // with all the release versions containing a change in the path info. This // is useful for navigating changes in a particular path across versions. ExtSnykApiReleases = "x-snyk-api-releases" // ExtSnykDeprecatedBy is used to annotate a path in a resource version // spec with the subsequent version that deprecates it. This may be used // by linters, service middleware and API documentation to indicate which // version deprecates a given version. ExtSnykDeprecatedBy = "x-snyk-deprecated-by" // ExtSnykSunsetEligible is used to annotate a path in a resource version // spec which is deprecated, with the sunset eligible date: the date after // which the resource version may be removed and no longer available. ExtSnykSunsetEligible = "x-snyk-sunset-eligible" )
const ( // SunsetWIP is the duration past deprecation after which a work-in-progress version may be sunset. SunsetWIP = 0 // SunsetExperimental is the duration past deprecation after which an experimental version may be sunset. SunsetExperimental = 24 * time.Hour // SunsetBeta is the duration past deprecation after which a beta version may be sunset. SunsetBeta = 91 * 24 * time.Hour // SunsetGA is the duration past deprecation after which a GA version may be sunset. SunsetGA = 181 * 24 * time.Hour )
const ( // ExtSnykIncludeHeaders is used to annotate a response with a list of // headers. While OpenAPI supports header references, it does not yet // support including a collection of common headers. This extension is used // by vervet to include headers from a referenced document when compiling // OpenAPI specs. ExtSnykIncludeHeaders = "x-snyk-include-headers" )
const SpecGlobPattern = "**/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/spec.yaml"
SpecGlobPattern defines the expected directory structure for the versioned OpenAPI specs of a single resource: subdirectories by date, of the form YYYY-mm-dd, each containing a spec.yaml file.
Variables ¶
var DefaultPivotDate = MustParseVersion("2024-10-15")
DefaultPivotDate is the default pivot date after which the versioning strategy changes.
var ErrNoMatchingVersion = fmt.Errorf("no matching version")
ErrNoMatchingVersion indicates the requested version cannot be satisfied by the declared versions that are available.
Functions ¶
func ComponentsEqual ¶ added in v8.0.1
func ComponentsEqual(x, y interface{}) bool
func ExtensionString ¶
ExtensionString returns the string value of an OpenAPI extension.
func IncludeHeaders ¶
IncludeHeaders adds response headers included with the ExtSnykIncludeHeaders extension property.
func IsExtensionNotFound ¶
IsExtensionNotFound returns bool whether error from ExtensionString is not found versus unexpected.
func LoadVersions ¶
LoadVersions loads all Vervet-compiled and versioned API specs from a filesystem root and returns them.
func Merge ¶
Merge adds the paths and components from a source OpenAPI document root, to a destination document root.
TODO: This is a naive implementation that should be improved to detect and resolve conflicts better. For example, distinct resources might have localized references with the same URIs but different content. Content-addressible resource versions may further facilitate governance; this also would facilitate detecting and relocating such conflicts.
TODO(next-release):
- This function is suitable for overlay merging scenarios only.
- Component merging should be removed. Use Collator for safe component merging.
func RemoveElements ¶
func RemoveElements(doc *openapi3.T, excludes ExcludePatterns) error
RemoveElements removes those elements from an OpenAPI document matching the given exclude patterns.
func RemoveRefs ¶
func RemoveRefs(target interface{}) error
RemoveRefs removes all $ref locations from an OpenAPI document object fragment. If the reference has already been resolved, this has the effect of "inlining" the formerly referenced object when serializing the OpenAPI document.
func ResolveRefsWithoutSourceName ¶
func ResolveRefsWithoutSourceName(t *openapi3.T, componentRef openapi3.ComponentRef) string
ResolveRefsWithoutSourceName resolves references without the source url/file name in ref background: this was the way kin-openapi used to resolve references, but it was changed in the recent versions(v0.127.0) to include the filename in the ref name. Although this method prevents conflicts, it causes existing specs to break.
func ToSpecJSON ¶
ToSpecJSON renders an OpenAPI document object as JSON.
func ToSpecYAML ¶
ToSpecYAML renders an OpenAPI document object as YAML.
func VersionDateStrings ¶
VersionDateStrings returns a slice of distinct version date strings for a slice of Versions. Consecutive duplicate dates are removed.
func WithGeneratedComment ¶
WithGeneratedComment prepends a comment to YAML output indicating the file was generated.
Types ¶
type Collator ¶
type Collator struct {
// contains filtered or unexported fields
}
Collator merges resource versions into a single OpenAPI document.
func NewCollator ¶
func NewCollator(options ...CollatorOption) *Collator
NewCollator returns a new Collator instance.
func (*Collator) Collate ¶
func (c *Collator) Collate(rv *ResourceVersion) error
Collate merges a resource version into the current result.
type CollatorOption ¶
type CollatorOption func(*Collator)
CollatorOption defines an option when creating a Collator.
func StrictTags ¶
func StrictTags(strict bool) CollatorOption
StrictTags defines whether a collator should enforce a strict conflict check when merging tags.
func UseFirstRoute ¶
func UseFirstRoute(useFirstRoute bool) CollatorOption
UseFirstRoute determines whether a collator should use the first matching path in the result when merging paths. When true, the first matching path goes into the collated result, similar to how a routing table matches a path. When false, a conflicting path route will result in an error.
Path variable names do not differentiate path routes; /foo/{bar} and /foo/{baz} are regarded as the same route.
type Document ¶
Document is an OpenAPI 3 document object model.
func NewDocumentFile ¶
NewDocumentFile loads an OpenAPI spec file from the given file path, returning a document object.
func NewResolvedDocument ¶
NewResolvedDocument returns a Document that has already been loaded and references resolved from the given URL. The URL is provided to indicate the document's origin in logging and error messages.
func (*Document) LoadReference ¶
func (d *Document) LoadReference(relPath, refPath string, target interface{}) (_ string, returnErr error)
LoadReference loads a reference from refPath, relative to relPath, into target. The relative path of the reference is returned, so that references may be chain-loaded with successive calls.
func (*Document) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (*Document) RelativePath ¶
RelativePath returns the relative path for resolving references from the file path location of the top-level document: the directory which contains the file from which the top-level document was loaded.
func (*Document) ResolveRefs ¶
ResolveRefs resolves all Ref types in the document, causing the Value field of each Ref to be loaded and populated from its referenced location.
type ExcludePatterns ¶
ExcludePatterns defines patterns matching elements to be removed from an OpenAPI document.
type Inliner ¶
type Inliner struct {
// contains filtered or unexported fields
}
Inliner inlines the component.
func (*Inliner) Inline ¶
Inline inlines all the JSON References previously indicated with AddRef in the given OpenAPI document.
func (*Inliner) ProcessCallbackRef ¶
func (in *Inliner) ProcessCallbackRef(ref *openapi3.CallbackRef) error
func (*Inliner) ProcessExampleRef ¶
func (in *Inliner) ProcessExampleRef(ref *openapi3.ExampleRef) error
func (*Inliner) ProcessHeaderRef ¶
func (*Inliner) ProcessParameterRef ¶
func (in *Inliner) ProcessParameterRef(ref *openapi3.ParameterRef) error
func (*Inliner) ProcessRequestBodyRef ¶
func (in *Inliner) ProcessRequestBodyRef(ref *openapi3.RequestBodyRef) error
func (*Inliner) ProcessResponseRef ¶
func (in *Inliner) ProcessResponseRef(ref *openapi3.ResponseRef) error
func (*Inliner) ProcessSchemaRef ¶
func (*Inliner) ProcessSecuritySchemeRef ¶
func (in *Inliner) ProcessSecuritySchemeRef(ref *openapi3.SecuritySchemeRef) error
type Lifecycle ¶
type Lifecycle int
Lifecycle defines the release lifecycle.
const ( // LifecycleUnreleased means the version has not been released yet. LifecycleUnreleased Lifecycle = iota // LifecycleReleased means the version is released. LifecycleReleased Lifecycle = iota // LifecycleDeprecated means the version is deprecated. LifecycleDeprecated Lifecycle = iota // LifecycleSunset means the version is eligible to be sunset. LifecycleSunset Lifecycle = iota // ExperimentalTTL is the duration after which experimental releases expire // and should be considered sunset. ExperimentalTTL = 90 * 24 * time.Hour )
func ParseLifecycle ¶
ParseLifecycle parses a lifecycle string into a Lifecycle type, returning an error if the string is invalid.
type RefIndex ¶
type RefIndex struct {
// contains filtered or unexported fields
}
RefIndex indexes the distinct references used in an OpenAPI document.
func NewRefIndex ¶
NewRefIndex returns a new reference index on an OpenAPI document.
type ResourceVersion ¶
type ResourceVersion struct { *Document Name string Version Version // contains filtered or unexported fields }
ResourceVersion defines a specific version of a resource, corresponding to a standalone OpenAPI specification document that defines its operations, schema, etc. While a resource spec may declare multiple paths, they should all describe operations on a single conceptual resource.
type ResourceVersions ¶
type ResourceVersions struct {
// contains filtered or unexported fields
}
ResourceVersions defines a collection of multiple versions of a resource.
func LoadResourceVersions ¶
func LoadResourceVersions(epPath string) (*ResourceVersions, error)
LoadResourceVersions returns a ResourceVersions slice parsed from a directory structure of resource specs. This directory will be of the form:
resource/ +- 2021-01-01 +- spec.yaml +- 2021-06-21 +- spec.yaml +- 2021-07-14 +- spec.yaml
The resource version stability level is defined by the ExtSnykApiStability extension value at the top-level of the OpenAPI document.
func LoadResourceVersionsFileset ¶
func LoadResourceVersionsFileset(specYamls []string) (*ResourceVersions, error)
LoadResourceVersionFileset returns a ResourceVersions slice parsed from the directory structure described above for LoadResourceVersions.
func (*ResourceVersions) At ¶
func (rv *ResourceVersions) At(vs string) (*ResourceVersion, error)
At returns the ResourceVersion matching a version string. The version of the resource returned will be the latest available version with a stability equal to or greater than the requested version, or ErrNoMatchingVersion if no matching version is available.
func (*ResourceVersions) Name ¶
func (rv *ResourceVersions) Name() string
Name returns the resource name for a collection of resource versions.
func (*ResourceVersions) Versions ¶
func (rv *ResourceVersions) Versions() VersionSlice
Versions returns each Version defined for this resource.
type SpecVersions ¶
type SpecVersions struct {
// contains filtered or unexported fields
}
SpecVersions stores a collection of versioned OpenAPI specs.
func LoadSpecVersions ¶
func LoadSpecVersions(root string) (*SpecVersions, error)
LoadSpecVersions returns SpecVersions loaded from a directory structure containing one or more Resource subdirectories.
func LoadSpecVersionsFileset ¶
func LoadSpecVersionsFileset(epPaths []string) (*SpecVersions, error)
LoadSpecVersionsFileset returns SpecVersions loaded from a set of spec files.
func (*SpecVersions) At ¶
func (sv *SpecVersions) At(v Version) (*openapi3.T, error)
At returns the OpenAPI document that matches the given version. If the version is not an exact match for an API release, the OpenAPI document effective on the given version date for the version stability level is returned. Returns ErrNoMatchingVersion if there is no release matching this version.
func (*SpecVersions) Versions ¶
func (sv *SpecVersions) Versions() VersionSlice
Versions returns the distinct API versions in this collection of OpenAPI documents.
type Stability ¶
type Stability int
Stability defines the stability level of the version.
const ( // StabilityWIP means the API is a work-in-progress and not yet ready. StabilityWIP Stability = iota // StabilityExperimental means the API is experimental and still subject to // drastic change. StabilityExperimental Stability = iota // StabilityBeta means the API is becoming more stable, but may undergo some // final changes before being released. StabilityBeta Stability = iota // StabilityGA means the API has been released and will not change. StabilityGA Stability = iota )
func MustParseStability ¶
MustParseStability parses a stability string into a Stability type, panicking if the string is invalid.
func ParseStability ¶
ParseStability parses a stability string into a Stability type, returning an error if the string is invalid.
func (Stability) Compare ¶
Compare returns -1 if the given stability level is less than, 0 if equal to, and 1 if greater than the caller target stability level.
func (Stability) Resolvable ¶
type Version ¶
Version defines an API version. API versions may be dates of the form "YYYY-mm-dd", or stability tags "beta", "experimental".
func MustParseVersion ¶
MustParseVersion parses a version string into a Version type, panicking if the string is invalid.
func ParseVersion ¶
ParseVersion parses a version string into a Version type, returning an error if the string is invalid.
func (Version) AddDays ¶
AddDays returns the version corresponding to adding the given number of days to the version date.
func (Version) Compare ¶
Compare returns -1 if the given version is less than, 0 if equal to, and 1 if greater than the caller target version.
func (Version) DateString ¶
DateString returns the string representation of the version date in YYYY-mm-dd form.
func (Version) DeprecatedBy ¶
DeprecatedBy returns true if the given version deprecates the caller target version.
func (*Version) LifecycleAt ¶
LifecycleAt returns the Lifecycle of the version at the given time. If the time is the zero value (time.Time{}), then the following are used to determine the reference time:
If VERVET_LIFECYCLE_AT is set to an ISO date string of the form YYYY-mm-dd, this date is used as the reference time for deprecation, at midnight UTC.
Otherwise `time.Now().UTC()` is used for the reference time.
The current time is always used for determining whether a version is unreleased.
type VersionIndex ¶
type VersionIndex struct {
// contains filtered or unexported fields
}
VersionIndex provides a search over versions, resolving which version is in effect for a given date and stability level.
func NewVersionIndex ¶
func NewVersionIndex(vs VersionSlice) (vi VersionIndex)
NewVersionIndex returns a new VersionIndex of the given versions. The given VersionSlice will be sorted.
func (*VersionIndex) Deprecates ¶
func (vi *VersionIndex) Deprecates(q Version) (Version, bool)
Deprecates returns the version that deprecates the given version in the slice.
func (*VersionIndex) Resolve ¶
func (vi *VersionIndex) Resolve(query Version) (Version, error)
Resolve returns the released version effective on the query version date at the given version stability. Returns ErrNoMatchingVersion if no version matches.
Resolve should be used on a collection of already "compiled" or "collated" API versions.
func (*VersionIndex) ResolveForBuild ¶
func (vi *VersionIndex) ResolveForBuild(query Version) (Version, error)
ResolveForBuild returns the most stable version effective on the query version date with respect to the given version stability. Returns ErrNoMatchingVersion if no version matches.
Use ResolveForBuild when resolving version deprecation and effective releases _within a single resource_ during the "compilation" or "collation" process.
func (*VersionIndex) ResolveGAorBetaStability ¶ added in v8.7.5
func (vi *VersionIndex) ResolveGAorBetaStability(query Version) (Version, error)
ResolveGAorBetaStability returns the GA or beta version effective on the query version date at the given version date. Returns ErrNoMatchingVersion if no version matches or if query stability is not GA.
func (*VersionIndex) Versions ¶
func (vi *VersionIndex) Versions() VersionSlice
Versions returns each Version defined.
type VersionSlice ¶
type VersionSlice []Version
VersionSlice is a sortable slice of Versions.
func (VersionSlice) Less ¶
func (vs VersionSlice) Less(i, j int) bool
Less implements sort.Interface.
func (VersionSlice) Strings ¶
func (vs VersionSlice) Strings() []string
Strings returns a slice of string versions.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
Package config supports configuring the Vervet Underground service.
|
Package config supports configuring the Vervet Underground service. |
internal
|
|
backstage
Package backstage supports vervet's integration with Backstage to automatically populate API definitions in the catalog info from compiled versions.
|
Package backstage supports vervet's integration with Backstage to automatically populate API definitions in the catalog info from compiled versions. |
cmd
Package cmd provides subcommands for the vervet CLI.
|
Package cmd provides subcommands for the vervet CLI. |
handler
Package handler contains the HTTP handlers that serve Vervet Underground responses.
|
Package handler contains the HTTP handlers that serve Vervet Underground responses. |
scraper
Package scraper provides support for scraping OpenAPI versions from services.
|
Package scraper provides support for scraping OpenAPI versions from services. |
storage
Package storage provides common functionality supporting Vervet Underground storage.
|
Package storage provides common functionality supporting Vervet Underground storage. |
storage/disk
Package disk provides an implementation of the storage used in Vervet Underground that uses a local filesystem.
|
Package disk provides an implementation of the storage used in Vervet Underground that uses a local filesystem. |
storage/s3
Package s3 provides an implementation of Vervet Underground storage backed by Amazon S3.
|
Package s3 provides an implementation of Vervet Underground storage backed by Amazon S3. |
Package versionware provides routing and middleware for building versioned HTTP services.
|
Package versionware provides routing and middleware for building versioned HTTP services. |