isabella232 / oas-style-guide

Freshworks OpenAPI 2.0 Style Guide

Lint rules to validate Open API 2.0 Specification using 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