This repository contains Spectral rules for linting Trimble OpenAPI specification documents. These rules are a companion to the Trimble Web API Standards.
Using the Spectral CLI requires NodeJS. This ruleset is tested with NodeJS 16.x.
See the Spectral installation instructions for complete details.
npm install -g @stoplight/spectral-cliYou can specify the ruleset directly on the command line:
spectral lint -r https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yaml <api definition file>Or you can create a Spectral configuration file (.spectral.yaml) that references the ruleset:
extends:
- https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yamlLint and output the results to an html file:
spectral lint ./openapi.yaml \
--ruleset https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yaml \
--format html > ./results.html
Lint the test spec locally
spectral lint ./examples/v3.0/petstore.yaml \
--ruleset ./spectral.yaml \
--format html > ./results.html
spectral lint ./examples/v3.0/petstore.yaml --ruleset ./spectral.yaml
spectral lint ./examples/v3.0/petstore.yaml \
--ruleset ./spectral-owasp.yaml
Warn if the spec version is less than 3.0
Warn if spec version is not 3.0 or higher
Tag names cannot use Pascal Case
Tag names cannot use Camel Case
Tag names cannot have version information
Operation summaries and descriptions should not match. Descriptions should be longer than summaries.
All POST methods should have a 201 response.
All DELETE methods should have a 204 response.
All 400 responses must include a response body.
Learn about writing rules here: https://docs.stoplight.io/docs/spectral/d3482ff0ccae9-rules
Learn about custom function here: https://docs.stoplight.io/docs/spectral/a781e290eb9f9-custom-functions
JSONPath documentation: https://goessner.net/articles/JsonPath/index.html
Useful web based tool for testing youe JSONPath values: https://jsonpath.com/
Petstore examples are from OpenAPI Initiative