Валидатор Swagger 2.0

Что считается успехом для Swagger 2.0

Для файла 2.0 проверка версии считается пройденной при наличии ключа swagger на верхнем уровне. Инструмент не проверяет, что значение равно "2.0", поэтому неверный номер он не поймает. Помимо версии, нужны info.title, info.version и объект paths.

Поля, специфичные для Swagger 2.0, такие как host, basePath, schemes, definitions и securityDefinitions, не проверяются. Отсутствующий host или повреждённый блок definitions не будут отмечены.

Пример

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

Поле версии, info и paths присутствуют, поэтому ошибок нет. Отчёт показывает одно предупреждение:

Документ по-прежнему признаётся корректным, потому что предупреждения не блокируют валидность. Ключи расширений вендора, например x-internal, допустимы в Swagger 2.0, поэтому их можно оставить.

Миграция с 2.0

Если вы планируете перейти на OpenAPI 3.x, вставьте преобразованный файл в то же поле и сравните результаты. Проверка та же, только поле openapi заменяет swagger. Для самой миграции используйте полноценный конвертер и линтер, потому что этот инструмент не переводит настройки definitions или host.

Когда достаточно быстрой проверки

Определения Swagger 2.0 годами живут в репозиториях и правятся вручную. Быстрая структурная проверка полезна, когда вы принимаете такой файл от кого-то, когда инструмент отказывается его загружать и вы подозреваете отсутствующее поле или когда объединяете два файла и хотите убедиться, что в результате остались разделы info и paths. Для полных правил 2.0, включая definitions и настройки безопасности, используйте специализированный линтер.

Помните, что чистый отчёт говорит только о структуре. Операции без ответов, неверные типы параметров и неразрешённые ссылки лежат за пределами этой проверки, поэтому протестируйте файл также в своём инструменте документации или генерации кода.