Dokumentieren einer Funktion, die ein JSON mit Yard rendert?

Question

Wenn ich eine Funktion, die diese zurückgibt:

render :json => @orders.as_json(include: [{:user => {only: :id}}], :only => [:id, :status_id]) 

ich es so bin Dokumentation:

# @return [JSON] includes the id, the order status id and the id of the associated user 

Ich frage mich, ob es einen besseren Weg des Dokuments ist, wie die zurück JSON aussehen wird .

Answer 1

Wenn Sie also an der Dokumentation Ihrer API interessiert sind, gehe ich davon aus, dass Sie auch an Tests interessiert sind, damit Ihre API-Endpunkte wahrscheinlich getestet werden. Ich würde vorschlagen, dass Sie Rspec API Documentation verwenden. Wenn Sie Rspec nicht verwenden, würde ich Apipie versuchen. Mit diesen beiden Tools können Sie sicherstellen, dass Ihre API-Dokumentation konsistent ist und auf dem neuesten Stand ist.