REST API documentation best practices for complex schemas

Question

I have an API I want to document properly so other developers can easily understand how to implement it.

The problem:

I have a resource which is v