Updating documentation

trimble-oss · Aug 25, 2023 · 7ce22fb · 7ce22fb
1 parent 06c3510
commit 7ce22fb
Show file tree

Hide file tree

Showing 3 changed files with 216 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -18,47 +18,37 @@ npm install -g @stoplight/spectral-cli
 
 ### Usage
 
+#### Production ruleset
+
 You can specify the ruleset directly on the command line:
 
 ```bash
 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:
+#### Develop Branch
 
-```yaml
-extends:
-  - https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yaml
-```
+Recently we have implemented a `develop` branch to allow for more broad testing. Any changes and additions will be pushed to the develop branch to allow for testing, validation and teams make changes before deploying new rule changes to the `main` branch. Access the `develop` ruleset at the following url:
 
-### Example
+`https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/develop/spectral.yaml`
 
-Lint and output the results to an html file:
+Example use in the command line:
 
 ```bash
-spectral lint ./openapi.yaml \
-    --ruleset https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yaml \
-    --format html > ./results.html
-
+spectral lint -r https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/develop/spectral.yaml <api definition file>
 ```
 
-Lint the test spec locally
-
-```bash
-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
+#### Extend the ruleset
 
+You can create a Spectral configuration file (`.spectral.yaml`) that references the ruleset:
 
+```yaml
+extends:
+  - https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yaml
 ```
 
+In this way you can create a custom ruleset that extends the Trimble ruleset.
+
 ## Trimble Rules
 
 #### ✅ tdp-minimum-spec-version

diff --git a/docs/RULES.md b/docs/RULES.md
@@ -0,0 +1,201 @@
+# OpenAPI Style Guidelines
+
+## Table of Contents
+
+<!-- toc -->
+
+- [OAS Rules](#oas-rules)
+  * [no-$ref-siblings](#no-ref-siblings)
+- [Trimble HTTP API Standard](#trimble-http-api-standard)
+  * [tas-api-server-url-invalid](#tas-api-server-url-invalid)
+  * [tas-api-server-url-version-invalid](#tas-api-server-url-version-invalid)
+  * [tas-openapi-v3-schema-properties-names-camel-case](#tas-openapi-v3-schema-properties-names-camel-case)
+  * [tas-no-http-verbs-in-path](#tas-no-http-verbs-in-path)
+  * [tas-structured-data-format](#tas-structured-data-format)
+  * [tas-structured-data-format-support-json-response-body](#tas-structured-data-format-support-json-response-body)
+  * [tas-check-queryparameter-in-endpoint](#tas-check-queryparameter-in-endpoint)
+  * [tas-operation-delete-204-status-code](#tas-operation-delete-204-status-code)
+  * [tas-operation-400-response-body](#tas-operation-400-response-body)
+  * [tas-check-content-type-for-206-get-response-code](#tas-check-content-type-for-206-get-response-code)
+  * [tas-standard-error-payload](#tas-standard-error-payload)
+  * [tas-check-description-for-all-error-responses](#tas-check-description-for-all-error-responses)
+  * [tas-check-description-for-all-success-responses](#tas-check-description-for-all-success-responses)
+  * [tas-check-for-content-type-in-put-and-post-responses](#tas-check-for-content-type-in-put-and-post-responses)
+  * [tas-delete-must-not-return-body](#tas-delete-must-not-return-body)
+- [Trimble Developer Program](#trimble-developer-program)
+  * [tdp-minimum-spec-version](#tdp-minimum-spec-version)
+  * [tdp-tag-pascal-case](#tdp-tag-pascal-case)
+  * [tdp-tag-camel-case](#tdp-tag-camel-case)
+  * [tdp-tag-no-versions](#tdp-tag-no-versions)
+  * [tdp-operation-summary-description](#tdp-operation-summary-description)
+  * [tdp-operation-post-201-202-status-code](#tdp-operation-post-201-202-status-code)
+  * [tdp-operation-400-response-body](#tdp-operation-400-response-body)
+  * [tdp-http-response-code](#tdp-http-response-code)
+  * [tdp-does-spec-contains-valid-http-verbs:](#tdp-does-spec-contains-valid-http-verbs)
+  * [tdp-spec-should-not-be-empty](#tdp-spec-should-not-be-empty)
+  * [tdp-check-for-path-parameters-in-parameter-block](#tdp-check-for-path-parameters-in-parameter-block)
+  * [tdp-check-for-response-in-every-request](#tdp-check-for-response-in-every-request)
+  * [tdp-invalid-symbol-in-path](#tdp-invalid-symbol-in-path)
+
+<!-- tocstop -->
+
+## OAS Rules
+
+### no-$ref-siblings
+
+Disable the OAS no ref rule
+
+## Trimble HTTP API Standard
+
+[Trimble HTTP API Standards on Github](https://github.com/trimble-oss/api-standards)
+
+[Trimble HTTP API Standards](https://api-standards.trimble-pnp.com/)
+
+### tas-api-server-url-invalid
+
+Server URLs should follow Trimble API Standards presented in Cloud URL Structure Summary
+
+https://api-standards.trimble-pnp.com/api-standard/http#url-structure
+
+### tas-api-server-url-version-invalid
+
+API Version must include the major version and MUST NOT include the minor version
+
+https://api-standards.trimble-pnp.com/api-standard/http#url-versioning
+
+### tas-openapi-v3-schema-properties-names-camel-case
+
+All schema property names should be camel case.
+
+https://api-standards.trimble-pnp.com/api-standard/http#field-names
+
+### tas-no-http-verbs-in-path
+
+Resource path should not contain HTTP verbs
+
+https://api-standards.trimble-pnp.com/api-standard/http#avoiding-actions-in-resource-names
+
+### tas-structured-data-format
+
+All APIs returning structured data should support JSON as the default format
+
+https://api-standards.trimble-pnp.com/api-standard/http#data-from-apis-bodies-returned-from-gets-posts-puts
+
+### tas-structured-data-format-support-json-response-body
+
+All APIs returning structured data should support JSON as the default format.
+
+https://api-standards.trimble-pnp.com/api-standard/http#data-from-apis-bodies-returned-from-gets-posts-puts
+
+### tas-check-queryparameter-in-endpoint
+
+Resource path should not contain query parameter
+
+https://api-standards.trimble-pnp.com/api-standard/http#url-parameters
+
+### tas-operation-delete-204-status-code
+
+All DELETE methods should have a 204 response
+
+https://api-standards.trimble-pnp.com/api-standard/http#successful-responses-2xx
+
+### tas-operation-400-response-body
+
+All 400 responses must include a response body
+
+https://api-standards.trimble-pnp.com/api-standard/http#client-error-responses-4xx
+
+### tas-check-content-type-for-206-get-response-code
+
+Check if the get response code 206 has content-type and content-range
+
+https://api-standards.trimble-pnp.com/api-standard/http#successful-responses-2xx
+
+### tas-standard-error-payload
+
+Standardize the error payload
+
+https://api-standards.trimble-pnp.com/api-standard/http#standard-error-payload
+
+### tas-check-description-for-all-error-responses
+
+Check for description for all error responses
+
+https://api-standards.trimble-pnp.com/api-standard/http#client-error-responses-4xx
+
+### tas-check-description-for-all-success-responses
+
+Check for description for all success responses
+
+https://api-standards.trimble-pnp.com/api-standard/http#successful-responses-2xx
+
+### tas-check-for-content-type-in-put-and-post-responses
+
+Check for content type in put and post response
+
+https://api-standards.trimble-pnp.com/api-standard/http#data-from-apis-bodies-returned-from-gets-posts-puts
+
+### tas-delete-must-not-return-body
+
+Delete response must not return body
+
+https://api-standards.trimble-pnp.com/api-standard/http#http-verbs
+
+## Trimble Developer Program
+
+### tdp-minimum-spec-version
+
+Warn if spec version is not 3.0 or higher
+
+### tdp-tag-pascal-case
+
+Tag names cannot use Pascal Case
+
+### tdp-tag-camel-case
+
+Tag names cannot use Camel Case
+
+### tdp-tag-no-versions
+
+Tag names cannot have version information
+
+### tdp-operation-summary-description
+
+Operation summaries and descriptions should not match.
+Descriptions should be longer than summaries.
+
+### tdp-operation-post-201-202-status-code
+
+All POST methods should have a 201 or 202 response.
+
+https://api-standards.trimble-pnp.com/api-standard/http#successful-responses-2xx
+
+### tdp-operation-400-response-body
+
+All 400 responses must include a response body.
+
+### tdp-http-response-code
+
+All APIs should return a valid http response code (Additional ruleset)
+
+### tdp-does-spec-contains-valid-http-verbs:
+
+Spec should contain only valid http verbs (Additional ruleset)
+
+### tdp-spec-should-not-be-empty
+
+Restrict empty spec(Additional ruleset)
+
+### tdp-check-for-path-parameters-in-parameter-block
+
+Check for appropriate path in parameters block as provided in the url (Additional case)
+
+### tdp-check-for-response-in-every-request
+
+Check if every request has their respective responses (Additional cases)
+
+https://api-standards.trimble-pnp.com/api-standard/http#service-responses
+
+### tdp-invalid-symbol-in-path
+
+Check for invalid symbols in the path (Additional Case)
diff --git a/package.json b/package.json
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "test": "jest",
-    "update-toc": "markdown-toc -i openapi-style-guide.md"
+    "update-toc": "markdown-toc -i docs/RULES.md"
   },
   "repository": {
     "type": "git",