desctiption & $ref вместе ломают кодогенерацию

[borgez]

по спеке или реф или description но не вместе, из-за этого ломается генерация в nswag

[vbauer]

@borgez Доброго времени суток, правильно понимаю что речь про https://github.com/RicoSuter/NSwag ? Он не является официальным генератором, входящим в поставку https://github.com/openAPITools/openapi-generator/ ? Можете пожалуйста предоставить больше информации о проблеме?

Можете уточнить на какой пункт спецификации вы ссылаетесь про недопустимость $ref и description? По https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.0/schema.json#L507 не вижу таких ограничений

Наши тесты показывают, что на генераторе csharp (https://openapi-generator.tech/docs/generators/csharp/) спецификация собирается корректно (как и нам многих других из официальной поставки openapi-generator-cli)

[borgez]

Доброе, подготовил пример

Тут можно посмотреть воспроизведение бага

Пример в спеках

Ссылаюсь на эту часть спеки, тут oneOf для properties, также по вашей ссылке если посмотреть $ref не является допустимым свойством в объекте

PS D:\work\2024\yandex-market-partner-api-bug-7> dotnet build
Determining projects to restore...
Restored D:\work\2024\yandex-market-partner-api-bug-7\Yandex.Market.Api.csproj (in 735 ms).
CSC : error REFITTER000: Refitter failed to generate code: System.InvalidCastException: Unable to cast object of type '
NJsonSchema.JsonSchema' to type 'NSwag.OpenApiPathItem'. [D:\work\2024\yandex-market-partner-api-bug-7\Yandex.Market.Ap
i.csproj]

Build FAILED.

CSC : error REFITTER000: Refitter failed to generate code: System.InvalidCastException: Unable to cast object of type '
NJsonSchema.JsonSchema' to type 'NSwag.OpenApiPathItem'. [D:\work\2024\yandex-market-partner-api-bug-7\Yandex.Market.Ap
i.csproj]
0 Warning(s)
1 Error(s)

Time Elapsed 00:00:05.51

[vbauer]

@borgez Спасибо за детальную информацию, проблема стала понятнее:

• В спецификации есть неочевидный момент "This object cannot be extended with additional properties and any properties added SHALL be ignored." https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object
• Генераторы входящие в https://github.com/OpenAPITools/openapi-generator/ интерпретируют в пользу игнорирования description'а (как и некоторые другие инструменты на которых проводим анализ спецификации), NSwag запрещает
• В спецификации версии 3.1 description официально разрешили добавлять к $ref, но как показывают внутренние тесты, некоторые генераторы из openapi-generator до сих пор имеют проблемы с 3.1

Мы возьмем задачу на подумать, но точных сроков пока что дать не могу. В данный момент возможны несколько вариантов решения:

• Использовать вместо NSwag генераторы из https://github.com/OpenAPITools/openapi-generator/ (если есть такая возможность)
• Реализовать предварительный процессинг спецификации по удалению description'ов (возможно есть еще какие-то расхождения с парсером или генератороми из проекта openapi-generator)