OpenAPI Metadata
Write rules about your OpenAPI metadata i.e. security
, servers
, info
, etc.
new SpecificationRule({
name: "require x-stability",
rule: (specificationAssertions) => {
specificationAssertions.requirement("has x-stability extension", () => {
// rule implementation
});
},
});
new SpecificationRule(options)
The following table describes the options object.
property | description | required | type |
---|---|---|---|
name | the name of the rule | yes | string |
matches | A function used to determine when this Rule should be applied. Return true to indicate this Rule should run. | no | (specification: Specification, ruleContext: RuleContext) => boolean |
docsLink | A link to the documentation for this ruleset. This will be used to show the user on a rule error. If there is a more specific docsLink (e.g. on a nested Rule), the more specific docsLink will be shown) | no | string |
rule | A function to define assertions for a specification. | yes | (specificationAssertions: SpecificationAssertions, ruleContext: RuleContext) => void |
matches
matches
is invoked with a Specification
and RuleContext
.
Example:
new SpecificationRule({
...,
// only runs on specifications that are not `x-stability: wip`
matches: (specification, ruleContext) => specification['x-stability'] !== 'wip',
...
});
specificationAssertions
specificationAssertions is used to define specification rules.
specificationAssertions[lifecycle](assertion)
new SpecificationRule({
...,
rule: (specificationAssertions) => {
// lifecycle rules that are available are added, changed, addedOrChanged, requirement and removed
specificationAssertions.added('contains a description', (specification) => {
if (!specification.value.description) {
throw new RuleError({
message: 'specifications must contain a description',
});
}
});
},
});
specificationAssertions also includes a number of common helper functions. These are invoked by defining a lifecycle trigger, and then the helper function. e.g. specificationAssertions[lifecycle].helperFunction()
.
The helper functions that are included are:
- matches
- matchesOneOf
All of these helper functions can be inverted by prefixing with .not
.
e.g. specificationAssertions.added.not.matches({ schema: { type: 'array' } })
matches
specificationAssertions[lifecycle].matches(shape)
Expects the operation to match a shape. The default behavior is to do a partial match.
import { Matchers } from '@useoptic/rulesets-base';
new SpecificationRule({
...,
rule: (specificationAssertions) => {
specificationAssertions.added.matches({
description: Matchers.string
});
},
});
matchesOneOf
specificationAssertions[lifecycle].matches(shape)
Expects the operation to match one of an array of shapes. The default behavior is to do a partial match.
import { Matchers } from '@useoptic/rulesets-base';
new SpecificationRule({
...,
rule: (specificationAssertions) => {
specificationAssertions.added.matches([
{ description: Matchers.string },
{ summary: Matchers.string },
]);
},
});