Документирование функции, которая отображает JSON с Yard?

Question

Если у меня есть функция, которая возвращает это:

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

Я документирую это так:

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

Мне интересно, есть ли лучший способ документировать, как будет выглядеть возвращаемый JSON.

Answer 1

Поэтому, если вы заботитесь о документации своего API, я предполагаю, что вы также заботитесь о тестировании, поэтому ваши конечные точки API, вероятно, проходят тестирование. Я бы посоветовал вам использовать Rspec API Documentation. Если вы сейчас не используете Rspec, я бы попробовал Apipie. Оба эти инструмента помогут обеспечить согласованность и актуальность документации по API.