openapi-lint v1.0

[mykulyak]

Overview

Let's discuss what we need to implement before advertising our linter to general audience.

• implement configurability
• add more rules

Configurability

The need for configurability should be pretty obvious. It is nearly impossible to check all APIs with a single set of rules.

I suggest to adopt the following terminology:

• rule - tests a certain aspect of an OpenAPI schema
• ruleset - a set of rules, applied together
• configuration - a way of defining rulesets

Configuration may be stored in JavaScript, JSON or YAML files.
Here is an example of how a linter configuration file may look (I used ESLint as a foundation):

name: legacy # name of the final ruleset defined by this configuration
description: A ruleset for legacy Fresha APIs
extends:
  - openapi-30
  - @fresha/openapi-lint-ruleset-jsonapi
rules:
  no-duplicate-enum-values: false # disable this rule
  jsonapi/resource-type-unique: 'error' # shortcut of setting severity
  jsonapi/naming-convention: # severity with extra options
    - error
    - name: kebab # name is a option, kebab is an option value
      exclude: # another option, which is an array
        - path-params

Rules and rulesets

Rulesets

• openapi30
• jsonapi
• fresha

openapi30 ruleset

• duplicate-tags - checks duplicate tag names in OAS schemas
• info-properties - checks the info.title and the info.description
• no-server-url-trailing-slash - server URLs must not end with trailing /
• no-unused-shared-components - stuff defined in the components section must be used somewhere in the same API
• (TODO) operation-has-id - each operation must have a valid ID
• operation-id-is-unique - operation IDs must be unique within a single API
• operation-success-response - operation must define a 'success' responses (2xx, 3xx or default)
• operation-tags-defined - tags used by an operation must be defined in the OAS schema
• operation-params-unique - operation parameters must be unique (by a combination of location + name) TODO: rules may be stricter, e.g. by requiring that names alone must be unique
• parameter-description - each parameter must have a description. By default is should be a non-empty string. TODO: optionally it may be restricted to not to include values like TBD, TODO etc.
• server-list - OAS schema must define a non-empty list of servers
• tags-descriptions - each tag must contain a non-empty description. Optionally, placeholder words like TBD, TODO may be treated as empty strings as well
• (TODO, READER) no-duplicate-enums - checks that enumeration values are unique
• (TODO, READER) path-params-valid - checks if path parameters are valid (e.g. exist and have exactly the same names as defined in path items)
• (TODO, READER) params-unique - checks that parameters are unique
• (TODO) safe-markdown - checks that Markdown strings do not contain stuff like eval, scripts or links to ad tracking stuff
• (TODO) tags-sorting - ensures that API tags are sorted
• (TODO) enum-types - types of enum elements must be the same as the type of the enum itself
• (TODO) server-only-host - forbids using paths in server URLs (e.g. no https://api.example.com/my-api)
• (TODO) security - require definition of API security
• (TODO) require-schema-examples - require to specify examples for schema objects. By default, rejects examples of "trivial" elements like ints or floats, or booleans
• (TODO, READER) valid-examples - requires that either example or examples field is specified, but not both
• (TODO) standard-response-codes - use 200 for GETs, 201 for synchronous POSTs, 202 for asynchronous POSTs, 204 for (most) DELETEs, etc.

jsonapi ruleset

• json-api-content-type - JSON:API operations must define request bodies and responses for application/vnd.api+json content type
• (TODO) naming-convention - checks the naming of resource attributes and relationships. Allowed values are: snake, kebab or camel
• (TODO) resource-type - checks whether document type is set (both for request and resources)
• (TODO) resource-plural-names - forces to use plural names in resource types
• (TODO) document-structure - strict or laxed. strict required an API to conform with JSON:API schema, laxed allows e.g. for declaring jsonapi block as optional, or resource type in document bodies as optional.
• (TODO) resource-structure - strict or laxed. strict required an API to conform with JSON:API schema, laxed allows e.g. for declaring resource type in document bodies. Same for passing resources in relationship fields.
• (TODO) resource-unique-type - enforces resources within an API have distinct type
• (TODO) relationship-attributes - forbids passing IDs of related resources in attributes section
• (TODO) relationship-cardinality - checks whether relationship is a properly define 0-, 1- or N- relationships

fresha ruleset

• schema-audience-is-set - info.x-audience must be set to a valid value
• contact-properties - info.contact.name must be a name of a team
• schema-id-is-uuid - OAS schema must have info.x-id which has to be a UUID
• schemas-ids-are-unique - IDs of OAS schemas checked in the same run must be unique
• shared-schema-title-is-set - title of shared schemas must not be empty, and preferably must be identical to keys they are accessible in an OAS schema
• path-items-sort - path items must be sorted according to their path URLs
• shared-schema-sort - shared schemas must be sorted according to their keys
• schema-version-is-semver - OAS schema version must be a valid semver
• (TODO) object-schema-no-additional-properties - checks that every Schema which is an object, has additionalProperties: false defined
• (TODO) path-params-inline - forces us to define path parameters on the level of operation, not path items. This is because open_api_spex library does not look into parameters defined for path items
• (TODO) user-guide - forces to include a link to user's guide in #/externalDocs
• (TODO, DISCUSS) root-url - forces to define #/info/x-root-url
• (TODO) numeric-format - forces to define format of integer and number schemas
• (TODO) normalised-paths - forces to use clean path item URLs (i.e. starting with a slash, not ending with a slash, and not containing multiple consecutive slashes)
• (TODO) query-param-names - forces to use "identifier-like" names for query parameters. E.g. no param[key], or param.key, only param.
• (TODO) query-param-types - forces to define query parameters that are arrays, as arrays of only primitive types (e.g. no arrays of objects)
• (TODO) schema-complexity - limits the number of entities in an API, like schemas, endpoints, operations. This is to make developers split their APIs more granularly
• (TODO) prefer-response-code - prefers HTTP responses defined for specific HTTP codes, instead of defining the default response
• (TODO) jsonapi-resource-structure (need better name) - enforces that resources within an API, that are referenced from another resources, be split into XXXResourceID and XXXResource schemas

Miscellaneous

Some schema properties will be checked before the first rule applies.

• path item URLs (e.g. no query params, or empty parameter placeholders)
• TBD