spell-check
Since 0.0.1 · In the rulesets: Strict at warning, All at warning
This rule checks the spelling of the texts written for humans: titles, summaries and descriptions.
Rule details
The rule reports every misspelled word, with up to three suggested corrections, for example
Misspelled word 'recieve' in description (did you mean 'receive', 'relieve', 'reverie'?).
The issue points at the object whose text contains the word. The rule checks:
- the title, summary and description of the info object,
- the summary and description of path items, operations, tags, examples and references,
- the description of servers, server variables, parameters, request bodies, responses, headers, links, security schemes and external documentation,
- the title and description of schemas.
Descriptions are CommonMark: the rule checks their prose, and skips code spans, code blocks,
raw HTML and link destinations. Titles and summaries are plain text, in which backticked
spans are skipped, too. The rule also skips the tokens which are not plain words:
- URLs, e-mail addresses, paths, and file and domain names (
openapi.yaml,example.com), - identifiers:
snake_case,camelCaseand names with inner capitals (OpenAPI,PetStore), - acronyms, also in the plural (
JSON,APIs,ID's), - tokens with digits (
v2,401) and single letters.
The spell checker is a C++ port of Hunspell. By default it uses
the built-in English (US) dictionary from SCOWL (as shipped with
LibreOffice), extended with words common in API descriptions, such as webhook, endpoint,
namespace, nullable and json. Any Hunspell dictionary can be used instead.
The rule is in the strict and all rulesets. Turn it off when the texts are written in a
language you have no dictionary for; to silence it for one object and its children, add
x-apigenie-lint-disable: [spell-check] to the object.
Configuration
An object with these optional properties:
words: extra words to accept, for example product names. A word is accepted as given, capitalized and in capitals:petstoreacceptspetstore,PetstoreandPETSTORE.dictionaryandaffix: paths of a Hunspell dictionary (.dic) and its affix file (.aff) to use instead of the built-in dictionary. They go together. Dictionaries in UTF-8, ISO-8859-1, ISO-8859-2 and ISO-8859-15 are supported.suggestions: how many corrections to suggest for a word, from 0 to 10 (default 3). Suggestions are the costly part of the rule; on a very large document with many unknown words,0makes it about ten times faster.
commands:
lint:
rules:
spell-check:
- warning
- words: [petstore, Fluffy]
commands:
lint:
rules:
spell-check:
- warning
- dictionary: dictionaries/en_GB.dic
affix: dictionaries/en_GB.aff
Examples
Good. Every word is in the dictionary, and the code span is skipped.
paths:
/users:
get:
summary: Retrieve a list of users
description: This operation retrieves the `users` of the system as JSON.
Bad. Three misspelled words.
paths:
/users:
get:
summary: Retrive a list of users
description: This operation retrives a list of users from the sytem.
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
spell-check: off