Валідатор OpenAPI
Перевірте документ OpenAPI 3.0, 3.1 або 3.2 чи Swagger 2.0 у форматі YAML або JSON й отримайте зведення його кінцевих точок і схем. Валідатор перевіряє обов’язкові поля, відповідність шаблонів шляхів параметрам шляху, розташування параметрів, коди відповідей, повторювані ідентифікатори операцій і кожне локальне $ref, а також указує розташування кожної проблеми.
Поширені запитання
Що перевіряє валідатор?
Валідатор перевіряє версію openapi або swagger, info.title і info.version, наявність слеша на початку шляхів, відповідність кожного {parameter} у шляху обов’язковому параметру шляху й навпаки, назви та розташування параметрів, коди стану й описи відповідей, повторювані параметри, повторювані значення operationId, а також те, що кожне локальне $ref вказує на щось у документі.
Це повна перевірка специфікації за схемою JSON?
Ні. Інструмент перевіряє наведені вище структурні правила, які допомагають виявити більшість помилок у документах, написаних вручну, але не звіряє кожне поле з офіційною метасхемою й не перевіряє вміст ваших схем.
Що показує зведення?
Версію специфікації та API, заголовок, таблицю всіх кінцевих точок із методом, шляхом, operationId, зведенням і кодами відповідей, а також назви схем у components.schemas або визначень у Swagger 2.0.
Чи переходить інструмент за зовнішніми посиланнями?
Ні. Посилання на інші файли чи URL-адреси не завантажуються й не відображаються у звіті. У вставленому документі обробляються лише посилання, що починаються з #.
Чим відрізняються помилки від попереджень?
Помилки означають порушення правила специфікації, наприклад відсутній опис відповіді або неоголошений параметр шляху. Попередження вказують на дозволені, але зазвичай ненавмисні речі, як-от операція GET із тілом запиту або документ без жодного operationId.
Чи змінює OpenAPI 3.1 перелік обов’язкового?
Так. В OpenAPI 3.1 і 3.2 для операції більше не потрібен об’єкт responses, а документ може містити webhooks або components замість paths. Валідатор застосовує ці правила, якщо поле openapi починається з 3.1 або 3.2.