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

Рекомендации по исправлению предупреждений OpenAPI Lint

Документ создан на основе анализа redocly lint api/openapi.yaml

Текущее состояние​

После исправления parameter-description:

ПравилоКоличествоСтатус
paths-kebab-case148 → 0Исправлено
boolean-parameter-prefixes59Опционально
parameter-description271 → 0Исправлено
operation-summary1Легко исправить
no-server-example.com1Легко исправить
no-http-verbs-in-paths1Легко исправить

Итого: 210 предупреждений (было 481)

1. paths-kebab-case (148 шт) — ИСПРАВЛЕНО​

Проблема​

Пути используют snake_case вместо kebab-case:

/daily_report → /daily-report
/mobile_tsd_data → /mobile-tsd-data
/tasks_members → /tasks-members

Почему важно​

  • Стандарт REST API — Google, Microsoft, GitHub API используют kebab-case
  • Читаемость URL — подчёркивания _ хуже видны в ссылках (особенно подчёркнутых)
  • Единообразие — улучшает developer experience (DX)
  • SEO — поисковые системы лучше обрабатывают kebab-case

Почему можно отложить​

  • Это breaking change для существующих клиентов
  • Требуется миграция на стороне потребителей API

Рекомендуемое решение​

Если API активно меняется — самое время переименовать:

  1. Переименовать файлы в api/paths/ (snake_case → kebab-case)
  2. Обновить ссылки в api/openapi.yaml
  3. На переходный период можно настроить алиасы (редиректы) на старые пути

2. boolean-parameter-prefixes (59 шт) — СПОРНО​

Проблема​

Булевые параметры не начинаются с is/has/can:

get_representations → is_representations_included
with_total → has_total
delete_mark → is_deleted

Почему важно​

  • Явно показывает, что параметр булевый
  • Общепринятая конвенция в программировании

Почему можно игнорировать​

  • Это стилистика, не функциональность
  • with_total достаточно понятно в контексте
  • Переименование — breaking change

Рекомендуемое решение​

Вариант А: Если готовы менять API — привести к стандарту Вариант Б: Отключить правило в redocly.yaml:

boolean-parameter-prefixes: off

3. Единичные предупреждения — ИСПРАВИТЬ ЛЕГКО​

ПравилоФайлПроблемаРешение
no-server-example.comopenapi.yamllocalhost в serversУдалить или заменить на placeholder
operation-summaryapi/paths/resource_file.yamlПустой summaryДобавить текст summary
no-http-verbs-in-pathsapi/paths/delete_subtasks_*.yamlГлагол delete в путиПереименовать путь (например, /subtasks-removal/)

Быстрые действия​

Убрать шум (без изменения API)​

Добавить в redocly.yaml:

apis:
  uit@v2:
    rules:
      boolean-parameter-prefixes: off  # 59 → 0

Полное исправление​

  1. Переименовать пути в kebab-case (148 файлов)
  2. Исправить единичные ошибки (3 шт)
  3. Решить по boolean-parameter-prefixes

Когда стоит исправлять​

Да:

  • API публичный и им пользуются внешние разработчики
  • Генерируете клиенты из OpenAPI (OpenAPI Generator, etc.)
  • Важна документация в Swagger/Redoc
  • API в процессе активного изменения (идеальный момент!)

Нет:

  • API внутренний и все знают как им пользоваться
  • Документация не публикуется
  • Цена миграции выше пользы от изменений

Ссылки​