Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/freshworks/oas-style-guide
https://github.com/freshworks/oas-style-guide
Last synced: 26 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/freshworks/oas-style-guide
- Owner: freshworks
- Created: 2021-07-21T10:26:55.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-12-26T18:31:42.000Z (almost 2 years ago)
- Last Synced: 2024-05-11T01:22:45.815Z (8 months ago)
- Size: 14.6 KB
- Stars: 0
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Freshworks OpenAPI 2.0 and 3.0.x Style Guide
Lint rules to validate Open API 2.0 and 3.0.x Specification using [Spectral](https://stoplight.io/open-source/spectral/). This extends ***spectral:oas*** package and adds custom rules on top of it.
# Usage
## Extending this style guide
### YAML
extends:
- https://unpkg.com/@freshworks/oas
rules:
...### JSON
{
"extends": [
"https://unpkg.com/@freshworks/oas"
],
"rules": {
...
}
}# Rules
Some rules are used from ***spectral:oas*** as it is and overridden the severity to **ERROR**. Rules that are not extended from ***spectral:oas*** will have prefix `fw-`.> Severity is set to **ERROR** for all rules defined below. Individual
> projects can override severity level to suit their needs.## info-description
OpenAPI object info `description` must be present and non-empty string.
## info-contact
Info object should contain `contact` object.
## operation-tags
Operation should have non-empty `tags` array.
## operation-tag-defined
Operation tags should be defined in global tags.
## operation-operationId
Operation should have an `operationId`.
## fw-info-license
Info object should contain `license` object
## fw-operation-summary
Each operation should have `summary`
## fw-schema-properties-example
Schema properties should have an example value defined
## fw-properties-underscore-case
Schema properties should be in underscore case
## fw-ensure-no-legacy-tags
Tags should not have legacy in its name
## fw-path-kebab-case
Path should be in kebab case.
> Private APIs follows the convention of `/api/_/...` . One underscore (`_`) followed by `/api/` is allowed for private APIs as an exception.
## fw-path-param-underscore-case
Path parameter should be in underscore case
## fw-query-param-underscore-case
Query parameter should be in underscore case
## fw-form-param-underscore-case
Form data parameter should be in underscore case