Unexpected $ref warning when a definition is declared and used once about openapi-validator HOT 5 CLOSED

🎉 This issue has been resolved in version 0.33.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

from openapi-validator.

At IBM, we use OpenAPI definitions to generate SDKs. One of our primary use-cases for this tool is to ensure that an API definition is fit for SDK Generation (the higher quality the API definition, the higher quality the generated SDK).

This warning you've run into is one that we've added specifically for that purpose. Using a $ref for a response provides us with a meaningful name we can use for a response model in the generated SDK. Without it, the name is automatically generated and is less-than-ideal for the UX of the SDK.

Since you are not likely generating SDKs, then I agree - in this scenario you don't really need to use a named reference. To remove the warning, you can turn off this rule in your configuration file.

Let me know if you have any other questions!

from openapi-validator.

Thanks @dpopp07 for detailed clarification, this totally makes sense to me. It would be great if this could be documented, to mention that the usage of $ref is to achieve a better data model naming when generating SDKs instead of definition reusability.

from openapi-validator.

That's a fair request, I will update the README to reflect this.

from openapi-validator.

@dpopp07 ^^

from openapi-validator.