Як автоматично перевіряти OpenAPI-специфікацію лінтером і впроваджувати стайлгайд API?

Стайлгайд API («ресурси в множині», «поля в snake_case», «кожна помилка має опис») у вікі мало хто читає. Якщо API описано специфікацією OpenAPI, правила можна перевіряти автоматично, як код лінтером.

Spectral - лінтер для OpenAPI (і AsyncAPI) з набором вбудованих правил і власними правилами:

# .spectral.yaml
extends: ["spectral:oas"]

rules:
  operation-description: error

  paths-kebab-case:
    description: Шляхи мають бути в kebab-case
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-{}]+)+$"

  properties-snake-case:
    description: Властивості схем - snake_case
    severity: warn
    given: $.components.schemas[*].properties[*]~
    then:
      function: casing
      functionOptions: { type: snake }

  errors-documented:
    description: Кожна операція описує відповідь 4xx
    severity: warn
    given: $.paths[*][*].responses
    then:
      function: schema
      functionOptions:
        schema: { anyOf: [{ required: ["400"] }, { required: ["404"] }, { required: ["422"] }] }

npx @stoplight/spectral-cli lint openapi.json

given - JSONPath до частини документа, then - перевірка (pattern, casing, truthy, schema, власні функції на JavaScript).

Що варто перевіряти:

• узгодженість: однаковий стиль назв, однакова пагінація й формат помилок у всіх ендпойнтах;
• повноту: описи операцій, приклади, задокументовані помилки й автентифікація;
• безпеку: кожна операція має схему безпеки, немає ендпойнтів без автентифікації випадково;
• заборонені практики: дієслова в шляхах, 200 з тілом помилки, відсутність обмеження розміру сторінки.

У CI разом з лінтером - пошук змін, що ламають клієнтів: порівняння специфікації гілки зі специфікацією основної гілки (інструменти на кшталт oasdiff). Видалене поле, новий обов'язковий параметр, змінений тип - помилка збирання, якщо зміна не позначена як навмисна.

Як впроваджувати:

• починати з попереджень, а не помилок, - інакше існуюче API не пройде перевірку;
• нові правила - як error лише для нових ендпойнтів чи після виправлення старих;
• стайлгайд у вигляді набору правил Spectral - виконуваний, і його можна перевикористати між командами (публікуючи як npm-пакет).

Для Laravel з генерацією специфікації (Scramble): експорт специфікації в CI → лінтинг → порівняння з основною гілкою. Так правила застосовуються до реального API, а не лише до документації.

Докладніше в документації: Spectral: лінтер для OpenAPI