Responses

A ResponseRule allows you to write assertions around the response status codes in your API Specification.

new ResponseRule({
  name: "prevent response removal",
  rule: (responseAssertions) => {
    responseAssertions.removed("not remove response", () => {
      throw new RuleError({
        message: "cannot remove an response",
      });
    });
  },
});

new ResponseRule(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	`(response: Response, 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	`(responseAssertions: ResponseAssertions, ruleContext: RuleContext) => void`

matches

matches is invoked with a Response and RuleContext.

Example:

new ResponseRule({
  ...,
  // only matches responses with content type 'application/json' and status code 201 in post operations
  matches: (response, ruleContext) => (
    ruleContext.operation.method === 'post' &&
    response.statusCode === '201'
  ),
  ...
});

responseAssertions

responseAssertions is used to define response rules.

responseAssertions[lifecycle](assertion)

new ResponseRule({
  ...,
  rule: (responseAssertions) => {
    // lifecycle rules that are available are added, changed, addedOrChanged, requirement and removed
    responseAssertions.added('contain description', (response) => {
      if (!response.value.description) {
        throw new RuleError({
          message: 'response must contain a description',
        });
      }
    });
  },
});

responseAssertions also includes a number of common helper functions. These are invoked by defining a lifecycle trigger, and then the helper function. e.g. responseAssertions[lifecycle].helperFunction().

The helper functions that are included are:

hasResponseHeaderMatching

All of these helper functions can be inverted by prefixing with .not.

e.g. responseAssertions.added.not.hasResponseHeaderMatching('X-Application', { description: Matchers.string })

hasResponseHeaderMatching

responseAssertions[lifecycle].hasResponseHeaderMatching(headerName, shape)

Expects the operation to match a shape. The default behavior is to do a partial match.

import { Matchers } from '@useoptic/rulesets-base';
 
new ResponseRule({
  ...,
  rule: (responseAssertions) => {
    responseAssertions.added.hasResponseHeaderMatching('X-Application', {
      description: Matchers.string
    });
  },
});

responseAssertions.header

responseAssertions.header is used to define response header rules.

responseAssertions.header[lifecycle](assertion)

new ResponseRule({
  ...,
  rule: (responseAssertions) => {
    // lifecycle rules that are available are added, changed, addedOrChanged, requirement and removed
    responseAssertions.header.added('contains a description', (header) => {
      if (!header.value.description) {
        throw new RuleError({
          message: 'header must contain a description',
        });
      }
    });
  },
});

Response Body

A ResponseBodyRule allows you to write assertions about the shape of the response bodies:

new ResponseBodyRule({
  name: "prevent response body removal",
  rule: (responseBodyAssertions) => {
    responseBodyAssertions.body.removed("not remove response", () => {
      throw new RuleError({
        message: "cannot remove an response",
      });
    });
  },
});

new ResponseBodyRule(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	`(response: ResponseBody, 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	`(responseBodyAssertions: ResponseBodyAssertions, ruleContext: RuleContext) => void`

matches

matches is invoked with a ResponseBody and RuleContext.

Example:

new ResponseBodyRule({
  ...,
  // only matches responses with content type 'application/json' and status code 201 in post operations
  matches: (response, ruleContext) => (
    ruleContext.operation.method === 'post' &&
    response.contentType === 'application/json' &&
    response.statusCode === '201'
  ),
  ...
});

responseBodyAssertions.body

responseBodyAssertions.body is used to define response rules.

responseBodyAssertions.body[lifecycle](assertion)

new ResponseBodyRule({
  ...,
  rule: (responseBodyAssertions) => {
    // lifecycle rules that are available are added, changed, addedOrChanged, requirement and removed
    responseBodyAssertions.body.added('contain description', (response) => {
      if (!response.value.description) {
        throw new RuleError({
          message: 'response bodies must contain a description',
        });
      }
    });
  },
});

responseBodyAssertions.body also includes a number of common helper functions. These are invoked by defining a lifecycle trigger, and then the helper function. e.g. responseBodyAssertions.body[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. responseBodyAssertions.body.added.not.matches({ schema: { type: 'array' } })

matches

responseBodyAssertions.body[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 ResponseBodyRule({
  ...,
  rule: (responseBodyAssertions) => {
    responseBodyAssertions.body.added.matches({
      description: Matchers.string
    });
  },
});

matchesOneOf

responseBodyAssertions.body[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 ResponseBodyRule({
  ...,
  rule: (responseBodyAssertions) => {
    responseBodyAssertions.body.added.matches([
      { description: Matchers.string },
      { summary: Matchers.string },
    ]);
  },
});

responseBodyAssertions.property

responseBodyAssertions.property is used to define response body property rules. You can write a rule about all properties (including request body properties) using the PropertyRule.

responseBodyAssertions.property[lifecycle](assertion)

new ResponseBodyRule({
  ...,
  rule: (responseBodyAssertions) => {
    // lifecycle rules that are available are added, changed, addedOrChanged, requirement and removed
    responseBodyAssertions.property.added('contains a type', (property) => {
      if (!property.value.type) {
        throw new RuleError({
          message: 'properties must contain a type',
        });
      }
    });
  },
});

responseBodyAssertions.schema

responseBodyAssertions.schema is used to define rules on any schema in a response body. Schemas can exist on the root response body, as an object field, array item and on polymorphic types (oneOf, anyOf, allOf).

responseBodyAssertions.schema[lifecycle](assertion)

new ResponseBodyRule({
  ...,
  rule: (responseBodyAssertions) => {
    // lifecycle rules that are available are added, changed, addedOrChanged, requirement and removed
    responseBodyAssertions.schema.added('contains a type', (schema) => {
      if (!schema.value.flatSchema.type) {
        throw new RuleError({
          message: 'schemas must contain a type',
        });
      }
 
      // schemas also contain the location of where the schema is located
      // Other examples include type === 'oneOf', 'array', etc
      if (schema.location.context.type === 'field' && schema.location.context.required) {
        // On field types, the context also includes required and key
        throw new RuleError({
          message: 'cannot add required fields',
        });
      }
    });
  },
});

Request Documentation