Линтер
Spectral

§1Что такое линтер описания

Spectral читает файл описания OpenAPI и проверяет его по набору правил. Он не запускает сервис и не отправляет запросов — работает только с текстом контракта. Поэтому он проверяет только то, что записано в описании, и не видит того, что проявляется лишь в поведении сервиса.

npx @stoplight/spectral-cli@6.16.3 lint openapi/openapi.yaml --fail-severity=warn

No results with a severity of 'warn' or higher found!

Обратите внимание на закреплённую версию @6.16.3: если её не указать, очередной выпуск линтера может добавить правило, и сборка упадёт без изменений в коде проекта. То же требование к внешним инструментам встречалось в главах 3.4 и 5.2.

§2Готовый набор spectral:oas

Писать правила с нуля не нужно: в Spectral встроен набор spectral:oas — десятки проверок для описаний OpenAPI. Он ловит и формальные ошибки (описание не соответствует схеме формата), и содержательные упущения.

В файле настроек проекта эти правила перечислены отдельно, чтобы повысить их уровень до error: включены они и по умолчанию, но в этом проекте отсутствие контактов считается ошибкой, а не предупреждением.

§3Файл настроек проекта

extends:
  - spectral:oas

rules:
  info-contact: error
  info-description: error
  operation-operationId: error
  operation-tags: error
  path-params: error

  # Собственные правила проекта из docs/API_STYLE_GUIDE.md
  …

§4Своё правило: из чего состоит

Собственное правило описывается четырьмя частями. Разберём их на правиле про имена путей.

paths-no-verbs:
  description: URI MUST описывать ресурс существительным, а не действием.
  severity: error
  given: "$.paths"
  then:
    field: "@key"
    function: pattern
    functionOptions:
      notMatch: "/(get|create|update|delete|remove|add)[A-Za-z]*(/|$)"

§5Три правила учебного проекта

error-responses-use-problem-json:
  description: Ответы 4xx и 5xx MUST использовать application/problem+json.
  severity: error
  given: "$.paths[*][*].responses[?(@property.match(/^[45]/))]"
  then:
    field: content
    function: schema
    functionOptions:
      schema:
        type: object
        required: [application/problem+json]

Выражение в given читается так: во всех путях, во всех операциях, среди ответов взять те, чей код начинается с 4 или 5. Дальше у каждого проверяется, что в content есть ключ application/problem+json. Это правило из главы 4.1, доведённое до автоматической проверки.

json-properties-snake-case:
  description: Свойства JSON MUST быть записаны в snake_case.
  severity: error
  given: "$.components.schemas[*].properties"
  then:
    field: "@key"
    function: casing
    functionOptions:
      type: snake

Здесь используется готовая проверка casing — писать образец вручную не нужно. Правило проверяет имена свойств всех схем сразу, поэтому единообразие не приходится отслеживать вручную.

paths-no-verbs:  # разобрано в §4

Трёх собственных правил для учебного проекта достаточно. Набор пополняют тогда, когда одно и то же замечание повторяется на ревью: повторяющееся замечание переводят в правило.

§6Настоящий вывод на плохом контракте

Проверим, что правила работают. Возьмём описание учебного сервиса и намеренно испортим его в двух местах: переименуем created_at в createdAt и заменим адрес /api/v1/tickets/open на /api/v1/getTickets.

npx @stoplight/spectral-cli@6.16.3 lint bad.yaml --fail-severity=warn

bad.yaml
 209:22  error  paths-no-verbs              URI MUST описывать ресурс существительным,
                                            а не действием.  paths./api/v1/getTickets
 581:19  error  json-properties-snake-case  Свойства JSON MUST быть записаны в snake_case.
                                            components.schemas.Ticket.properties.createdAt

✖ 2 problems (2 errors, 0 warnings, 0 infos, 0 hints)

1. Строка и столбец. 209:22 — точное место в файле, можно открыть и поправить.
2. Уровень и имя правила. По имени правило находится в .spectral.yaml, а оттуда — в стандарте.
3. Текст описания. Тот же, что был записан в правиле: человек сразу видит, что именно нарушено.
4. Путь внутри документа. components.schemas.Ticket.properties.createdAt — где в структуре описания сидит нарушение.
5. Итог. Две ошибки — значит, ненулевой код возврата, и сборка не пройдёт.

§7Уровни и порог падения

У каждого правила есть уровень, а у запуска — порог, начиная с которого проверка считается провалившейся.

В учебном проекте запуск идёт с ключом --fail-severity=warn: падает не только на ошибках, но и на предупреждениях. Порог выбран строгий: описание учебного стенда небольшое, и держать его без замечаний проще, чем вести список известных предупреждений.

§8Чего линтер не проверяет

Ограничение то же, что у oasdiff из главы 5.2: линтер видит описание, а не поведение.

Этим определяется состав сборки, разобранный в главе 6.4: линтер, тесты и сравнение версий — три проверки, каждая из которых закрывает свою часть стандарта.