APIs in a kongctl declarative configuration file are defined in the apis block. To make sure every API is documented, you may want to validate that each one has a description.
Here is a sample ruleset file containing a single rule that accomplishes this:
rules:
api-description-defined:
description: "APIs must have a description"
given: $.apis[*]
severity: error
then:
field: description
function: truthy
The JSONPath selector specified in given selects every API under the apis key from the incoming file. For each of those objects, the truthy function checks that the description field is set.
Assume you have the following declarative configuration file (kong.yaml):
apis:
- ref: tasks-api
name: Task API
Validating this configuration against the example ruleset, stored in ruleset.yaml, results in the following violation:
kongctl lint -f kong.yaml -r ruleset.yaml
Result:
Linting Violations: 1
Failures: 1
kong.yaml:1:1: [error] APIs must have a description: `description` must be set
Adding a description to the API resolves this violation:
apis:
- ref: tasks-api
name: Task API
description: Create and track tasks
Run kongctl with the new ruleset:
kongctl lint -f kong.yaml -r ruleset.yaml; echo $?
Result:
When kongctl lint finds violations at or above the --fail-severity level, the command returns a non-zero exit code.
You can use this to stop a CI/CD pipeline before a problematic configuration is applied.
To lint multiple files, pass a directory to -f and use -R to process it recursively.