Custom Rules for API Standardization

Last modified on May 06, 2021

Available in SwaggerHub SaaS for organizations on the Enterprise plan and in SwaggerHub On-Premise 1.23 and later.

Organizations can add custom rules for the API standardization that will be used to validate OpenAPI definitions for compliance with API design guidelines. These rules can help you verify that:

  • a specific node exists in YAML, regardless of the value,

  • the node name or value matches (or does not match) a regular expression.

Each rule consists of a node path (such as $.info.version) and, optionally, a regular expression that defines valid values for this node. You can customize the rule severity and applicable OpenAPI versions.

Considerations

Custom standardization rules have the same limitations as the built-in rules:

  • They apply only to APIs, not to domains.

  • They check the YAML structure as is and do not resolve $refs.

Create a custom rule

To create rules, you must be an organization owner.

  1. Hover over the organization name in the SwaggerHub sidebar and click the Settings Settings button that appears. This will open the organization settings.

  2. Switch to the Standardization tab.

  3. Scroll to the bottom and click Add Custom Rule.

    Add Custom Rule
  4. Configure the rule (see the parameters below) and click Save.

    Tip: You can also test the rule directly in the rule editor.

After you create or edit a rule, click Save at the top of the Standardization page to re-scan your organization’s APIs.

Rule parameters

Rule parameters

Name

Required. A unique name for this rule, up to 35 characters. The name is also used as a prefix for the rule’s error message.

OpenAPI Version

Select whether the rule applies to OpenAPI 2.0, OpenAPI 3.0, or both. OpenAPI 2.0 and 3.0 definitions use a slightly different structure and keywords, so some validations may need separate rules for different OpenAPI versions.

Path Required

A JSONPath expression that specifies the target node or nodes to check. For example, $.info.version. Case-sensitive.

We use the jsonpath-plus library that supports some extra selectors in addition to the standard JSONPath syntax. See the jsonpath-plus documentation for the supported syntax.

Note: JSONPath filter expressions [?(...)] are not supported in "path exists" rules, but they are supported in regex-based rules.

Path Exists

Select this check box if you just want to check that the node is present, regardless of the value. For example, check that tag objects have a description specified. See also How "path exists" rules work below.

Regex

A regular expression to test against the result of the specified JSONPath. For example, ^\d+\.\d+\.\d+$.

Notes:

  • This option is available if the Path Exists option is unselected.

  • If the path expression returns an array, each array item is tested against this regular expression.

  • Regexes look for a partial match unless the pattern contains the ^ (beginning of value) and $ (end of value) anchors. For example, a matches any string that contains this character, but ^a$ matches the exact string "a".

  • Regexes are case-sensitive by default. For a case-insensitive match, use the format /pattern/i, for example, /https/i.

Must Match

Regular expression match type: "must match" (check box is selected) or "must not match" (unselected).

Rule Severity

Error or Warning. Errors will prevent the API from being published if the Require API to pass Standardization to be publishable option is selected in the Standardization settings.

Error Message

An optional additional error message displayed in the SwaggerHub editor, up to 130 chars. If omitted, the rule name is used as the error message. If both the name and the error message are specified, the name will prefix the error message. For example, given:

  • Rule name: Version

  • Error message: `info.version` must be major.minor.patch

the full error message in the editor will be:

Version -> `info.version` must be major.minor.patch

Try It Out

Use this section to test the rule against your existing APIs.

Enable Rule for Organization

Whether the rule is enabled or disabled.

Examples

Version must be major.minor.patch (digits only)

Path Required: $.info.version

Path Exists: unselected

Regex: ^\d+\.\d+\.\d+$

Must Match: selected

Paths should not end with a slash

Path Required: $.paths.*~

Path Exists: unselected

Regex: ^\/.+\/$

Must Match: unselected

Path names like /pets and /pets/{id} are considered valid, but /pets/ and /pets/{id}/ will be flagged.

How "path exists" rules work

"Path exists" rules verify the presence of a specific node or nodes in YAML. The specified JSONPath expression is first split into two components: the last component (the target key name) and everything that precedes it (let's call this "base path"). SwaggerHub then finds all the nodes with the "base path" and checks whether each of them contains the target key. The nodes that do not contain this key will fail the validation.

Sample rule: "201 responses to POST requests must include the Location header"

$.paths.*.post.responses.201.headers.Location
\__________________________________/ \______/
 find all the nodes at this path     and check whether
                                     they have this key

Keep in mind that the presence of intermediate nodes is not enforced. For example, the rule above will not flag 201 responses without headers – because these responses will not be found by the "base path" expression ….201.headers.

# Rule will flag this response
responses:
  201:
    description: Created
    headers:
      X-RateLimit-Remaining:
        type: string

# but not this response
responses:
  201:
    description: Created

In this example, the "Location header exists" rule needs to be implemented as two "path exists" rules in order to verify that: a) 201 responses have headers; and b) headers include the Location header:

Path exists:  $.paths.*.post.responses.201.headers

Path exists:  $.paths.*.post.responses.201.headers.Location

Test a rule

You can quickly test custom rules against existing APIs directly in the rule editor. To do that:

  1. Edit a rule or start creating a new one.

  2. Paste the YAML to test against, or click Import API and load an existing API.

    Note: Pasting works only if the path has not been specified yet.
  3. Enter the JSONPath and, optionally, a regular expression to test the value.

  4. The validation results will appear in the Try It Out section.

    Testing custom rules

The Try It Out section displays YAML nodes found by the specified JSONPath. Leading dashes (-) indicate individual matches. Note that a match can be a standalone value, a simple key: value node, an array, or a multi-property object (including nested objects). The error and warning icons in the gutter indicate the nodes that failed the validation.

The results may look differently depending on whether you test a "path exists" rule or a regex-based rule. For example, when testing the existence of tag descriptions ($.tags[*].description), the results would show all the tag objects ("base" nodes) and indicate those without the description property. However, when testing the values of tag descriptions against a regular expression, the results will show the descriptions themselves.

Delete a custom rule

Note: In SwaggerHub On-Premise, this is supported since v. 1.27.

  1. In the Custom Rules list, click next to the rule you want to delete and confirm the deletion.

  2. Click Save at the top of the Standardization page to save the changes.

    The 'Save' button

Enable or disable a rule

  1. Select or clear the check box next to the rule.

  2. Click Save at the top of the page to save the changes.

See Also

API Standardization

Highlight search results