Governance

The Governance tool validates the OpenAPI documents against spectral rulesets.

This tool is provided so that the Governance capabilities of API Connect can be used from API Agent. For example, validating the OpenAPI documents against spectral rulesets. Also, it can also be used to fix (remediate) spectral validation findings within an OpenAPI 3.0 document.

Tool details and limitations

The following are the Governance tool details and limitations:
  • To use this tool with on-premises installations of API Connect, enable Governance in the Management CR.
  • Currently, the Governance tool supports working the newest versions of rulesets in the Governance service. For example, you can validate an OpenAPI document with the newest version of a ruleset. However, you cannot specify an older version when you use prompt. This limitation also applies to the remediation operation for fixing validation findings in an OpenAPI document.
  • The remediation (with rulesets) operation of this tool uses AI-based remediation and can take some time. This time takes longer for larger, more complex OpenAPI documents. A default timeout of three minutes is applied. If remediation takes more than three minutes for an OpenAPI document, the tool times-out.
  • To accommodate the three-minute maximum duration of remediation, make sure that your cluster Ingress controller, Ingress Route, or HAProxy timeout settings does not timeout in less than three minutes.
The following features of Governance are made available in API Agent:

List Rulesets

You can list the spectral rulesets that are provided to you as part of Governance within your provider organization.

A table displays the following details about the rulesets:
  • Name
  • Version
  • Description
Example prompt

List rulesets
Next action suggested
  • Validate api {@filename} by using ruleset {ruleset}
  • Validate api {draft-api-name}:{draft-api-version} by using ruleset {ruleset}

List rules in a Ruleset

You can list all the individual rules that are part of the spectral rulesets available to you within your provider organization.

  • A table shows the following details about each rule within the specified ruleset:
    • Name
    • Description
Table 1. Parameters
Parameter Required Description Default
ruleset Yes The ruleset name, which you want to list the rules for. None
Example prompt

List rules in ruleset {ruleset}
Next action suggested
  • Validate api {@filename} by using ruleset {ruleset}
  • Validate api {draft-api-name}:{draft-api-version} by using ruleset {ruleset}

Validate an OpenAPI document by using rulesets

You can validate OpenAPI documents with spectral rulesets in your provider organization with the following options:
  • Using a local file attachment upload in the Visual Studio Code plug-in chat window.
  • Providing the name and version of an existing draft API within the provider organization of the user on the API Manager.

This operation displays the following details:

  • A brief summary of the number of spectral findings and their severity.
  • A validation report .CSV file that can be downloaded, containing the complete set of the following findings:
    • Rule and ruleset of the rule
    • A message that describes the validation finding that violates the rule.
    • Line number in the OpenAPI document corresponds to the finding.
    • Location (JSON path) of the finding within the OpenAPI document.
  • The findings and their locations also open in the PROBLEMS panel, as shown in following screenshot.

  • If the OpenAPI document is a local file, it automatically opens in the Visual Studio Code file editor. All spectral findings are highlighted in the file.
Table 2. Parameters
Parameter Required Description Default
input_file No The OpenAPI specification in YAML or JSON format to be validated. None
api_name No The name (info.x-ibm-name) of the draft API to be validated. None
api_version No The version (info.version) of the draft API to be validated. None
ruleset Yes List of rulesets to use in the validation. None
Example prompts

To validate a local file against a single Ruleset, run the following prompt:
validate api {@filename} using {ruleset} ruleset
To validate a draft API against a single Ruleset, run the following prompt:
Validate api {api-name}:{api-version} using {ruleset} ruleset
To validate a local file against two or more Rule sets, run the following prompt:
Validate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
To validate a draft API against multiple Rulesets, run the following prompt:
Validate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
Next action suggested
  • Remediate api {@filename} by using ruleset {ruleset}
  • Revalidate api {@filename} by using ruleset {ruleset}

Remediate (fix) an OpenAPI document that uses rulesets

If Governance validation of an OpenAPI document reveals findings based on spectral rulesets within your provider organization, you can use AI-based remediation to attempt to resolve these findings. Upload a local file in the Visual Studio Code plug-in chat window or specify an existing draft API on the API Manager.

This operation displays the following details:

  • An OpenAPI document file that can be downloaded that contains all the applied remediation that the AI-based remediation was able to fix automatically for the chosen rulesets.

  • Also, the remediated OpenAPI document file automatically opens in the Visual Studio Code file editor. The applied fixes get highlighted directly in the file.

  • The following details of each applied fix are shown in the AI RECOMMENDATIONS panel:

    • Path (JSON Path) to the recommendation
    • Recommendation (a description)
    • Explanation (explains the recommendation)
    • Details of the Spectral Rule that the recommendation comes from (Severity, Ruleset name, Rule name, and message).
Note:
  • The AI-based remediation is only supported for the spectral-owasp and spectral-oas rulesets from Governance. If prompted to remediate by using an unsupported ruleset, you receive a warning that the unsupported ruleset was not used in the chat response from the API Agent.
  • The tool expects that a valid OpenAPI 3.0 document is used as input. No warning is given if an invalid file is supplied. For example, supplying an AsyncAPI document as input against a ruleset with rules that apply to an OpenAPI document, and vice-versa.
  • You can run remediation multiple times on the same OpenAPI document to remediate an issue if it is not found initially.
  • Applying fixes through AI can introduce new violations of other spectral rules because the system does not automatically validate its fixes and recommendations against the rulesets after each change.
Table 3. Parameters
Parameter Required Description Default
input_file No The OpenAPI Specification in YAML or JSON format to be remediated. None
api_name No The name (info.x-ibm-name) of the draft API to be remediated. None
api_version No The version (info.version) of the draft API to be remediated. None
ruleset Yes List of rulesets to use in the remediation. None
Example prompts

To remediate a local file against a ruleset, run the following prompt:
Remediate api {@filename} using {ruleset} ruleset
To remediate a local file against two or more Rulesets, run the following prompt:
Remediate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
To remediate a draft API against a single Ruleset, run the following prompt:
Remediate api {api-name}:{api-version} using {ruleset} ruleset
To remediate a draft API against multiple Rulesets, run the following prompt:
Remediate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
Next action suggested
  • Reremediate api {@filename} by using ruleset {ruleset}
  • Validate api {@filename} by using ruleset {ruleset}