-
Notifications
You must be signed in to change notification settings - Fork 5
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
base: main
Are you sure you want to change the base?
Changes from 3 commits
ebccb59
6a2dc0f
3e16ac9
1c2279d
107c968
fd080fd
4c63c33
d12a07d
00af71f
50252e6
735b83a
e6dfb35
06c3510
7ce22fb
51388d7
1e64c5c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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. | ||
|
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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) |
Unchanged files with check annotations Beta
openapi: "3.0.0" | ||
info: | ||
Check warning on line 2 in examples/v3.0/petstore.yaml
|
||
version: 1.0.0 | ||
title: Swagger Petstore | ||
license: | ||
name: MIT | ||
servers: | ||
- url: http://petstore.swagger.io/v1 | ||
description: Everything about your Dogs | ||
paths: | ||
/pets: | ||
get: | ||
summary: List all pets | ||
operationId: listPets | ||
tags: | ||
- pets | ||
parameters: | ||
- name: limit | ||
in: query | ||
application/json: | ||
schema: | ||
$ref: "#/components/schemas/Error" | ||
post: | ||
summary: Create a pet | ||
operationId: createPets | ||
tags: | ||
- pets | ||
responses: | ||
"202": | ||
description: Null response | ||
schema: | ||
$ref: "#/components/schemas/Error" | ||
/pets/{petId}: | ||
get: | ||
summary: Info for a specific pet | ||
operationId: showPetById | ||
tags: | ||
- pets | ||
parameters: | ||
- name: petId | ||
in: path |
swagger: "2.0" | ||
Check warning on line 1 in examples/v2/petstore.yaml
|
||
info: | ||
Check warning on line 2 in examples/v2/petstore.yaml
|
||
version: 1.0.0 | ||
title: Swagger Petstore | ||
license: | ||
name: MIT | ||
host: petstore.swagger.io | ||
basePath: /v1 | ||
- application/json | ||
paths: | ||
/pets: | ||
get: | ||
summary: List all pets | ||
operationId: listPets | ||
tags: | ||
- pets | ||
parameters: | ||
- name: limit | ||
in: query | ||
description: unexpected error | ||
schema: | ||
$ref: "#/definitions/Error" | ||
post: | ||
summary: Create a pet | ||
operationId: createPets | ||
tags: | ||
- pets | ||
responses: | ||
"201": | ||
description: Null response | ||
schema: | ||
$ref: "#/definitions/Error" | ||
/pets/{petId}: | ||
get: | ||
summary: Info for a specific pet | ||
operationId: showPetById | ||
tags: | ||
- pets | ||
parameters: | ||
- name: petId | ||
in: path |
There was a problem hiding this comment.
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.