Перейти к основному содержимому

Spectral Ruleset for Yandex Cloud API Gateway

· 2 мин. чтения
Nikolay Matrosov
Nikolay Matrosov

Я сначала начал писать заголовок на русском, но получилось что-то типа «Набор правил для валидации специфичных для Яндекс Облака расширений, для интеграции с другими облачными сервисами, спецификации OpenAPI 3.0, используемой для конфигурации сервиса API Gateway.» Потом посмеялся и стер всё.

Если вы, как и я любите в голове валидировать YAML-конфиги и глазами считать количество пробелов, то наверняка давно мечтали об удобном инструменте, чтобы больше этого не делать. К счастью такие инструменты есть. Я выбрал Spectral от Spotlight.

Мне понравилось, что его можно легко расширить своим набором правил. Причем их можно писать не только как JSON Schema документы, но и просто на JavaScript. Что проще писать, поддерживать, а также дает простор для описания и валидации сложных случаев. Еще для него есть инструменты интеграции с VSCode и IDE от JetBrains. Но мой ruleset с ними не завелся. Если кто-то вдруг в курсе в чем может быть дело, напишите в комментариях. В итоге остается использовать консольную утилиту.

Как установить и использовать​

Чтобы установить саму CLI, выполните:

npm install -g @stoplight/spectral-cli

Затем нужно установить пакет с набором правил:

npm i --save-dev @nikolay.matrosov/yc-spectral-ruleset

Теперь нам нужно создать файл .spectral.yml в котором указать, какой набор правил использовать для валидации.

extends:
  - '@nikolay.matrosov/yc-api-gw-schema'

Все можно валидировать нашу OpenAPI спеку и убедиться, что все работает.

Для примера создадим новый API Gateway в облаке и скопируюем спецификацию оттуда.

openapi.yaml
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
servers:
- url: https://d5d92cevh5qmi34tdt2g.apigw.yandexcloud.net
paths:
  /:
    get:
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': Hello, World!
        http_code: 200
        http_headers:
          Content-Type: text/plain

Что же мы получим на выходе?

А то что этот минимальный пример не проходит наши довольно строгие правила валидации. И тут есть два пути: поправить ошибки или выключить правила, которые мы посчитаем излишне строгими.

Чтобы это сделать в .spectral.yml нужно добавить секцию overrides, где перечислить какие правила вы хотите отключить. Например, чтобы отключить все предупреждения со скриншота, нужно добавить следующие строки. (Ошибки уровня error лучше все-таки поправить. Хотя и эти правила можно отключить. Но зачем тогда линтер?)

.spectral.yml
overrides:
  - files:
      - "*.yaml"
    rules:
      info-contact: off
      info-description: off
      operation-description: off
      operation-operationId: off
      operation-tags: off

А еще в .spectral.yml можно описать свои правила в секции rules. Как это сделать можно прочитать тут.

Сам набор тут. Все баги и фичреквесты пишите на GitHub.