-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #22 from trimble-oss/develop
Adding CONTRIBUTION.md
- Loading branch information
Showing
6 changed files
with
1,051 additions
and
28 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.