Эта страница — каноническое руководство по lint документов OpenAPI и Swagger в браузере с DevUtilities. Вставьте спецификацию сверху во время чтения или перейдите к теме ниже. Проверка остаётся локальной — документы никогда не загружаются. Когда lint зелёный, передайте в Kiota SDK Engine для оценки готовности и предпросмотра команды generate.

OpenAPI Validator — клиентский линтер для OpenAPI 3 и Swagger 2 в JSON/YAML. Он сообщает VALID, VALID WITH WARNINGS или INVALID с диагностикой по путям, чтобы исправить блокеры до генерации SDK или импорта в шлюз.

Что вы получаете

• Разбирает документы OpenAPI 3.x и Swagger 2 (JSON или YAML)
• Баннер статуса: VALID / VALID WITH WARNINGS / INVALID
• Проверяет ключи версии, покрытие paths, servers и типичные структурные проблемы
• Только локальный lint — безопасно для внутренних API-спецификаций
• Прямая передача в Kiota SDK Engine для готовности к codegen

Используйте этот инструмент, когда

• Нужна быстрая предполетная проверка перед Microsoft Kiota или другими генераторами
• CI или чеклист PR требует читаемый lint зафиксированной спецификации
• Вы унаследовали файл Swagger 2 и хотите предупреждения о миграции до работы над OpenAPI 3
• Дублирующие operationId или сломанные $ref продолжают ломать codegen

Предпочитайте связанный инструмент, когда

• Нужна полная оценка готовности Kiota, матрица языков и конструктор CLI → Kiota SDK Engine
• Нужно только оформить JSON-полезную нагрузку → JSON Formatter
• Нужны массивы mock-ответов → JSON Generator

Генераторы кода (особенно Kiota) громко падают на структурных проблемах, которые упускает беглый взгляд на YAML. Сначала lint здесь, затем откройте Kiota SDK Engine для генераторной готовности.

Блокеры, которые нужно снять до codegen

• Дублирующий или отсутствующий operationId (коллизии имён методов)
• Отсутствующие или пустые responses на кодах успеха
• Неверный или висячий $ref в components
• Отсутствует ключ версии openapi/swagger или пустой объект paths
• Циклические ссылки schema (часто всплывают далее в Kiota)

Предупреждения, которые можно отложить

• Отсутствует servers[] — клиентам могут понадобиться переопределения --base-url
• Заметки миграции Swagger 2 — для новых API предпочитайте OpenAPI 3
• Скудные описания — качество документации, не блокеры разбора

Первый проход перед генерацией SDK.

1. Вставьте OpenAPI 3 или Swagger 2 как JSON или YAML в панель ввода.
2. Прочитайте статус: VALID, VALID WITH WARNINGS или INVALID.
3. Исправьте каждую ошибку в списке диагностики — начните с operationId, responses и сбоев $ref.
4. Повторяйте lint, пока статус не станет VALID или не останутся только приемлемые предупреждения.
5. Передайте очищенную спецификацию в Kiota SDK Engine для оценки, предпросмотра языка и команды kiota generate.
6. Зафиксируйте исправленный документ и при желании добавьте этот lint в чеклист PR.

Pull request’ы сливают правки OpenAPI, которые потом ломают ночную регенерацию SDK. Рецензенты не видят дублирующие operationId глазами.

Как этот инструмент решает проблему

1. Вставьте документ OpenAPI из PR в валидатор во время ревью.
2. Требуйте VALID (или только задокументированные предупреждения) перед approve.
3. Укажите дублирующие operationId и сломанные $ref в треде ревью с текстом диагностики.
4. После merge запустите Kiota в CI против того же документа.

Lint-гейт в человеческом темпе, ловящий тот же класс сбоев, что и генераторы — без загрузки спецификации.

Команда вот-вот запустит kiota generate и хочет уверенности, что документ не упадёт из-за имён или $ref.

Как этот инструмент решает проблему

1. Lint документа здесь, пока не исчезнет INVALID.
2. Передайте в Kiota SDK Engine и проверьте оценку OpenAPI Readiness.
3. Исправьте оставшиеся проблемы Kiota (циклические ссылки, стиль nullable) в диагностике Kiota.
4. Скопируйте сгенерированную CLI-команду, когда готовность приемлема.

Двухшаговый локальный процесс: структурный lint → готовность Kiota → generate на вашей машине.

Старый JSON Swagger 2 всё ещё питает шлюз. Стейкхолдеры хотят OpenAPI 3 до внедрения Kiota.

Как этот инструмент решает проблему

1. Вставьте документ Swagger 2 и отметьте предупреждения миграции.
2. Исправьте структурные INVALID, которые заблокируют любой конвертер.
3. Спланируйте миграцию на OpenAPI 3 для новых функций; держите Swagger 2 только пока он ограничен.
4. Снова lint результат OpenAPI 3 перед Kiota.

Ясный сигнал: Swagger 2 разбирается с предупреждениями — для новой SDK-работы предпочитайте OpenAPI 3.

Генераторы называют методы клиента по operationId. Дубликаты вызывают коллизии.

Почему это происходит

Две или более операции делят один operationId, либо operationId отсутствует там, где генератор требует его.

Диагностика

Ищите в документе повторяющиеся значения operationId. Kiota и этот линтер помечают коллизии — исправьте здесь до открытия SDK-движка.

Исправления

1. Назначьте уникальный operationId каждой операции (глагол + ресурс — частый шаблон).
2. Удалите неиспользуемые дублирующие paths, скопированные при правке.
3. При урезании под частичный SDK удаляйте конфликтующие paths, а не переименовывайте production ID наобум.

После переименования снова lint и перепроверьте готовность Kiota — имена методов в превью изменятся.

Операции без пригодных responses ломают типизированную генерацию клиентов.

Почему это происходит

Операция path опускает responses, либо успешные responses имеют пустой content {} без schema.

Диагностика

Проверьте карту responses каждой операции на записи 200/201 (или default) и убедитесь, что schema content разрешаются.

Исправления

1. Добавьте хотя бы один успешный response с media type application/json (или подходящим).
2. Укажите schema content на components.schemas через $ref вместо пустого content.
3. Документируйте ошибочные responses (4xx/5xx), когда клиенты должны их обрабатывать — предупреждения могут остаться при пропуске.

Неверные указатели $ref мешают разрешению schema во время lint и codegen.

Почему это происходит

$ref указывает на отсутствующий компонент, использует неверный JSON Pointer или образует цикл, который резолвер не может развернуть.

Диагностика

Пройдите каждый сбойный путь $ref в components.schemas / parameters / responses. Подтвердите, что целевой ключ существует и написание совпадает.

Исправления

1. Исправьте или заново создайте отсутствующую цель компонента.
2. Нормализуйте строки $ref к указателям #/components/...
3. Разорвите циклические ссылки, извлекая неглубокие DTO (далее действует гид Kiota по циклическим ссылкам).

Интерпретируйте баннер, прежде чем менять документ.

OpenAPI Validator и Kiota SDK Engine дополняют друг друга. Здесь — структурное здоровье; в Kiota — готовность генератора, матрица языков, выбор endpoints и экспорт CLI-команды.

• После VALID передайте или вставьте очищенную спецификацию в Kiota SDK Engine.
• Используйте диагностику Kiota для дублирующих operationId, циклических $ref и проблем стиля nullable.
• Скопируйте kiota generate из шага Kiota Generate — выпуск файлов по-прежнему через локальный Kiota CLI.
• Держите оба инструмента на клиенте, чтобы внутренние API-контракты не покидали браузер.

• Lint на каждом OpenAPI PR перед approve.
• Для новых API предпочитайте OpenAPI 3; Swagger 2 считайте legacy с предупреждениями миграции.
• Делайте operationId уникальным и стабильным — переименования трясут сгенерированных клиентов.
• Всегда давайте успешным responses разрешаемую schema.
• Снимите INVALID до открытия Kiota; далее используйте Kiota для генераторной готовности.
• Не загружайте внутренние спецификации в сторонний lint SaaS, если хватает этого локального пути.