If I have a function that returns this:
render :json => @orders.as_json(include: [{:user => {only: :id}}], :only => [:id, :status_id])
I am documenting it like this:
# @return [JSON] includes the id, the order status id and the id of the associated user
I am wondering if there is a better way of document how the returned JSON will look like.
So if you care about the documentation of you API I assume that you also care about testing so your API end points probably have test. I would suggest that you using Rspec API Documentation. If you are not currently using Rspec I would give Apipie a try. Both of these tools will help to insure that your API documentation is consistent and stays up to date.
