Documentare una funzione che rende un JSON con Yard?

Question

Se ho una funzione che restituisce questo:

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

sto documentando così:

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

Mi chiedo se c'è un modo migliore di documento, come il JSON restituita sarà simile .

Answer 1

Quindi, se ti interessa la documentazione della tua API, suppongo che ti interessi anche dei test, quindi i tuoi endpoint API probabilmente hanno un test. Ti suggerirei di utilizzare Rspec API Documentation. Se attualmente non utilizzi Rspec, darei una prova a Apipie. Entrambi questi strumenti ti aiuteranno ad assicurare che la tua documentazione API sia coerente e sia sempre aggiornata.