Плагин OpenAPI Generator Maven: цель $ref, указывающая на схему вместо объекта Response - SpecValidationException ⇐ JAVA

[Anonymous]

Проблема
Я использую плагин OpenAPI Generator Maven (v7.3.0) для генерации клиентского кода Java на основе удаленной спецификации OpenAPI. Сборка завершается сбоем из-за ошибок проверки, указывающих на то, что ссылки $ref ответа указывают на объекты схемы, а не на объекты ответа.
Сообщение об ошибке

Код: Выделить всё

[WARNING] There were issues with the specification. The option can be disabled via validateSpec
Error count: 2, Warning count: 4

Errors:
- paths.'/file/{pType}/{pCode}/{cCode}'(get).responses.200.$ref
target #/components/schemas/fileInfo is not of expected type Response

- paths.'/segment/{pType}/{pCode}/{sCode}'(get).responses.200.$ref
target #/components/schemas/sResponse is not of expected type Response

Текущая конфигурация
pom.xml

Код: Выделить всё

org.openapitools
openapi-generator-maven-plugin
7.3.0


File API Generator

generate


true
https://xxx.yyy.com/v3/api-docs
${project.parent-pom-dir}/contracts/
java
com.xxx.yyy.ing.client.api
com.xxx.yyy.ing.client.model

Структура спецификации OpenAPI (упрощенная)
Удаленная спецификация OpenAPI возвращает такие ответы:

Код: Выделить всё

paths:
/file/{pType}/{pCode}/{cCode}:
get:
responses:
200:
$ref: '#/components/schemas/fileInfo'  # ❌ Direct reference to schema

Среда

• Spring Boot: 2.7.8
• Java: 17
• Maven: 3.x
• Плагин OpenAPI Generator: 7.3.0
• Источник спецификации OpenAPI: удаленная конечная точка REST (не под моим контролем)

Вопросы

• Это ошибка в спецификации удаленного OpenAPI или в плагине есть настройка конфигурации для обработки этого шаблона?
• Следует ли мне загрузить спецификацию локально и исправить ее вручную, или есть способ преобразовать/исправить спецификацию программно во время сборки Maven?
• Сделает ли переход на версию плагина 5.x эту проверку менее строгой? (Мне нужен импорт javax.*, а не jakarta.* для совместимости с Spring Boot 2.7.8)
• Какова правильная структура OpenAPI 3.0 для определений ответов? Должно быть так:

Код: Выделить всё

# Option A: Direct schema reference (current - fails validation)
responses:
200:
$ref: '#/components/schemas/fileInfo'

# Option B: Wrapped in content/schema (standard?)
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/fileInfo'

Что я пробовал
Установить true — ошибки проверки все равно появляются
Проверил спецификацию OpenAPI 3.0 — подтверждает, что ответы должны использовать content.schema.$ref
Невозможно изменить удаленный API (это сторонняя служба)
Ожидаемое поведение
Плагин должен либо:

• успешно сгенерировать код из удаленной спецификации, ИЛИ
• предоставить способ автоматического исправления/преобразования спецификации во время генерации

Дополнительный контекст
Одна и та же удаленная конечная точка отлично работает с пользовательским интерфейсом Swagger и Postman, что позволяет предположить, что спецификация функциональна, несмотря на то, что она не является строго допустимой в соответствии со стандартами OpenAPI 3.0.

Подробнее здесь: https://stackoverflow.com/questions/798 ... -of-respon