Skip to main content

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.

propertydescriptionrequiredtype
namethe name of the ruleyesstring
matchesA function used to determine when this Rule should be applied. Return true to indicate this Rule should run.no(specification: Specification, ruleContext: RuleContext) => boolean
docsLinkA 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)nostring
ruleA 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 },
]);
},
});