spell-check

Since 0.9.0 · In the rulesets: Strict at warning, All at warning

This rule checks the spelling of the texts of a Swagger 2.0 document 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 summary (did you mean 'Receive', 'Relieve', 'Reverie'?). When there are no suggestions, the part in parentheses is omitted. The issue points at the object whose text contains the word. The rule checks:

  • the title and description of the info object,
  • the summary and description of operations,
  • the title and description of schemas,
  • the description of parameters, responses (but not response references), headers, security definitions, tags and external documentation objects.

Descriptions are Markdown (GFM in Swagger 2.0): 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 (swagger.yaml, example.com),
  • identifiers: snake_case, camelCase and names with inner capitals (PetStore),
  • acronyms, also in the plural (HTTP, 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 part of the strict and all rulesets.

The OpenAPI and AsyncAPI linters have rules of the same name, spell-check and spell-check.

Turn the rule off if your documentation is written in a language you have no dictionary for. To silence it for a single object and its children, add x-apigenie-lint-disable: [spell-check] to the object.

Configuration

This rule accepts an object with the following options:

  • words: extra words to accept, for example product names. A word is accepted as given, capitalized and in capitals: petstore accepts petstore, Petstore and PETSTORE.
  • dictionary and affix: 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, 0 makes it about ten times faster.

Configuration example

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        spell-check:
          - warning
          - words: [petstore]
            dictionary: path/to/en_GB.dic
            affix: path/to/en_GB.aff

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      summary: Receive the list of pets
      description: Returns the pets available for adoption.
      responses:
        '200':
          description: The list of pets.

Bad.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      summary: Recieve the list of pets
      description: Returns the pets availabel for adoption.
      responses:
        '200':
          description: The list of pets.

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.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        spell-check: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?