Валидатор 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 или definitions в Swagger 2.0.
Переход выполняется по внешним ссылкам?
Нет. Ссылки на другие файлы или URL не загружаются и не указываются в отчете. Разрешаются только ссылки, начинающиеся с #, внутри вставленного документа.
Чем отличаются ошибки от предупреждений?
Ошибки означают нарушение правила спецификации, например отсутствие описания ответа или необъявленный параметр пути. Предупреждения указывают на допустимые, но обычно нежелательные случаи, например операцию GET с телом запроса или документ без operationId.
Меняет ли OpenAPI 3.1 список обязательных элементов?
Да. В OpenAPI 3.1 и 3.2 объект responses для операции больше не обязателен, а документ может содержать webhooks или components вместо paths. Валидатор применяет эти правила, если значение поля openapi начинается с 3.1 или 3.2.