I’ve been working on a complex OpenAPI schema where I need to thoroughly describe the data processing handlers within the schema. However, I’ve encountered a significant limitation: the OpenAPI specification imposes a 300-character limit on the description field for each schema property.
To overcome this limitation, I attempted to reference external markdown files using variables and $refs, with the idea that the detailed descriptions would be stored externally and simply linked from within the schema. Unfortunately, this approach hasn’t worked as expected—the variables and references do not resolve correctly, and as a result, the descriptions are either not properly linked or not displayed at all.
Given that the primary goal is to ensure that the schema remains well-documented and fully descriptive, while also adhering to the OpenAPI specification, I’m now at a crossroads. I need a solution that allows for detailed documentation without hitting the character limit, possibly through better external file referencing or another workaround.
I’m seeking advice on how best to handle this situation. Any guidance on effective strategies for managing detailed descriptions in OpenAPI, or alternative approaches for referencing external documentation within the schema, would be greatly appreciated.
