Documenting a function that renders a JSON with Yard?

Question

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.

Janka

Did you find a better way? – Lastex

Answer 1

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.

Huei