Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Syncing new rules into main #34

Open
wants to merge 16 commits into
base: main
Choose a base branch
from
Open
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 14 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 for teams to 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
203 changes: 203 additions & 0 deletions docs/RULES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
# 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)
- [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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is set to severity: error, and should say MUST instead of "should"
All schema property names MUST 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is set to severity: error, and should say MUST instead of "should"


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)
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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",

Unchanged files with check annotations Beta

openapi: "3.0.0"
info:

Check warning on line 2 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

info-description

Info "description" must be present and non-empty string.

Check warning on line 2 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

info-contact

Info object must have "contact" object.
version: 1.0.0
title: Swagger Petstore
license:

Check warning on line 5 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

license-url

License object must include "url".
name: MIT
servers:
- url: http://petstore.swagger.io/v1
description: Everything about your Dogs
paths:
/pets:
get:

Check warning on line 16 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-description

Operation "description" must be present and non-empty string.
summary: List all pets
operationId: listPets
tags:
- pets

Check warning on line 20 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-tag-defined

Operation tags must be defined in global tags.
parameters:
- name: limit
in: query
application/json:
schema:
$ref: "#/components/schemas/Error"
post:

Check warning on line 48 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-description

Operation "description" must be present and non-empty string.
summary: Create a pet
operationId: createPets
tags:
- pets

Check warning on line 52 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-tag-defined

Operation tags must be defined in global tags.
responses:
"202":
description: Null response
schema:
$ref: "#/components/schemas/Error"
/pets/{petId}:
get:

Check warning on line 63 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-description

Operation "description" must be present and non-empty string.
summary: Info for a specific pet
operationId: showPetById
tags:
- pets

Check warning on line 67 in examples/v3.0/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-tag-defined

Operation tags must be defined in global tags.
parameters:
- name: petId
in: path
swagger: "2.0"

Check warning on line 1 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

tdp-minimum-spec-version

The spec version should be 3 or greater.

Check warning on line 1 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

openapi-tags

OpenAPI object must have non-empty "tags" array.
info:

Check warning on line 2 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

info-contact

Info object must have "contact" object.

Check warning on line 2 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

info-description

Info "description" must be present and non-empty string.
version: 1.0.0
title: Swagger Petstore
license:

Check warning on line 5 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

license-url

License object must include "url".
name: MIT
host: petstore.swagger.io
basePath: /v1
- application/json
paths:
/pets:
get:

Check warning on line 17 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-description

Operation "description" must be present and non-empty string.
summary: List all pets
operationId: listPets
tags:
- pets

Check warning on line 21 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-tag-defined

Operation tags must be defined in global tags.
parameters:
- name: limit
in: query
description: unexpected error
schema:
$ref: "#/definitions/Error"
post:

Check warning on line 42 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-description

Operation "description" must be present and non-empty string.
summary: Create a pet
operationId: createPets
tags:
- pets

Check warning on line 46 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-tag-defined

Operation tags must be defined in global tags.
responses:
"201":
description: Null response
schema:
$ref: "#/definitions/Error"
/pets/{petId}:
get:

Check warning on line 55 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-description

Operation "description" must be present and non-empty string.
summary: Info for a specific pet
operationId: showPetById
tags:
- pets

Check warning on line 59 in examples/v2/petstore.yaml

GitHub Actions / Lint (pull_request)

operation-tag-defined

Operation tags must be defined in global tags.
parameters:
- name: petId
in: path