Merge pull request #21 from trimble-oss/issue-17

Issue 17

CONTIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to the Trimble OpenAPI Spectral Rules
+
+If you would like to contribute to this project please read the [contributing guidelines](https://trimble-oss.github.io/contribute/guidelines/).
+
+## Issues
+
+- You are welcome to [submit an issue](https://github.com/trimble-oss/openapi-spectral-rules/issues) with a bug report or a feature request.
+- If you are reporting a bug, please indicate which version of the package you are using and provide steps to reproduce the problem.
+- If you are submitting a feature request, please indicate if you are willing or able to submit a PR for it.
+
+## Building and testing
+
+To build and test the project locally, clone the repo and issue the following commands
+
+```sh
+npm install
+npm test
+```
+
+## Adding new rules
+
+When you add a new rule there are a number of places you should consider including:
+
+- `spectral.yaml` should define the new rule, possibly pointing to a new function used by the rule.
+- `functions` directory to hold any new function for the rule.
+- `test\<rulename>.test.js` should test at least the error and no-error cases of the rule.
+- `openapi-style-guide.md` should be updated with the style guideline that the rule enforces.
+
+### spectral.yaml
+
+When creating new rules we have some conventions that should be followed. For rule properties:
+
+| Field   | Notes                                                                              |
+| ------- | ---------------------------------------------------------------------------------- |
+| name    | prefixes:                                                                          |
+|         | "`tdp-`" Trimble Developer Program                                                 |
+|         | "`tas-`/`tapi`" Trimble API Standards                                              |
+| formats | You can add formats, however, tdp has a warning rule on oas formats lower than 3.0 |
+
+Rule name convention, not really strict about this, but it should be something like:
+
+`{prefix}-{target}-{rule}`
+
+Where
+
+- **prefix**, origin of this rule, tdp or tas
+- **target**, what part of the spec does the rule apply to, `tag`, `path`, `operation`, etc. or compound like `tag-description` or `operation-params`
+- **rule**, extremely concise rule description, like `camel-case`, `no-versions`, `no-refs`, etc.
+
+### openapi-style-guide.md
+
+When adding a new rule, please add a section to the style guide that describes the rule. The section heading should match the rule name in the `spectral.yaml` file. For example, if the rule name is `tdp-tag-pascal-case` then the section should be `### tdp-tag-pascal-case`.

README.md

@@ -1,6 +1,6 @@
 # Trimble OpenAPI Spectral rules
 
-This repository contains Spectral rules for linting Trimble OpenAPI specification documents. These rules are a companion to the Trimble Web API Standards.
+This repository contains Spectral rules for linting Trimble OpenAPI specification documents. These rules are a companion to the Trimble Web API Standard.
 
 ## How to use the Spectral ruleset
 

openapi-style-guide.md

@@ -0,0 +1,69 @@
+# OpenAPI Style Guidelines
+
+## Table of Contents
+
+<!-- toc -->
+
+- [OpenAPI Style Guidelines](#openapi-style-guidelines)
+  - [Table of Contents](#table-of-contents)
+  - [OAS Rules](#oas-rules)
+    - [no-$ref-siblings](#no-ref-siblings)
+  - [Trimble HTTP API Standard](#trimble-http-api-standard)
+  - [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-delete-204-status-code](#tdp-operation-delete-204-status-code)
+    - [tdp-operation-400-response-body](#tdp-operation-400-response-body)
+
+<!-- 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/)
+
+## 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. [POST (create) - Successful Responses](https://api-standards.trimble-pnp.com/api-standard/http#successful-responses-2xx)
+
+### tdp-operation-delete-204-status-code
+
+All DELETE methods should have a 204 response.
+
+### tdp-operation-400-response-body
+
+All 400 responses must include a response body.