cph/rabl-oldRuby-шаблонизатор для генерации JSON и XML API с исправлением для CVE-2014-4671. Поддерживает партиалы, наследование и пользовательские узлы для гибкого построения ответов API.
RABL (Ruby API Builder Language) — это система шаблонов на Ruby для Rails и Padrino, предназначенная для генерации JSON, XML, MessagePack, PList и BSON. При использовании метода ActiveRecord 'to_json' мне часто хочется получить более выразительное и мощное решение для генерации API. Это особенно актуально, когда JSON-представление сложное или не соответствует точной схеме, определённой в базе данных.
В частности, я хочу легко:
Любой, кто пробовал метод 'to_json', используемый в ActiveRecord для генерации JSON-ответа, ощущал боль этого ограничительного подхода. RABL — это общая система шаблонов, созданная для решения этих проблем путём совершенно нового подхода к генерации ответов API.
В основе RABL лежит следование принципам MVC путём переноса представления данных API в представление (view) вашего приложения. Чтобы разобраться с распространёнными заблуждениями о RABL, пожалуйста, ознакомьтесь с нашим руководством по пониманию RABL, которое поможет прояснить любую путаницу, связанную с этим проектом.
v0.8.0 (выпущена 14 февраля 2013 г.) удаляет зависимость от multi_json и полагается на Oj (или JSON) в качестве парсера JSON. Упрощает код, удаляет зависимость, но вам, возможно, потребуется удалить все ссылки на MultiJson.
v0.6.14 (выпущена 28 июня 2012 г.) требует использования render_views с RSpec для тестирования шаблонов. В противном случае контроллер просто передаст команду render, как это делается с шаблонами ERB.
Установите RABL как гем:``` gem install rabl
или добавьте в ваш Gemfile:```ruby
# Gemfile
gem 'rabl'
# Also add either `oj` or `yajl-ruby` as the JSON parser
gem 'oj'
и выполните bundle install для установки зависимости.
Если вы используете Rails 2.3.8 (и выше), Rails 3.X или Padrino, RABL работает без настройки.
Важно: В Padrino убедитесь, что гем rabl указан после гема padrino в вашем Gemfile, иначе Rabl не зарегистрируется должным образом как шаблонизатор.
Для Sinatra или любого другого фреймворка на основе tilt, просто зарегистрируйте:```ruby Rabl.register!
и RABL будет инициализирован и готов к использованию. Для использования с Sinatra ознакомьтесь с руководством [Sinatra Usage](https://github.com/nesquena/rabl/wiki/Setup-for-Sinatra).
## Обзор ##
Вы можете использовать RABL для генерации API на основе JSON и XML из любого объекта Ruby. С помощью RABL данные обычно извлекаются преимущественно из моделей (независимо от ORM), а представление вывода API описывается внутри шаблона представления с помощью простого Ruby DSL. Это позволяет отделить данные от JSON или XML, которые вы хотите вывести.
После установки RABL (описано выше) вы можете создать шаблон представления RABL и затем легко отрисовать его из приложений Sinatra, Padrino или Rails из контроллера (или маршрута). Используя [Padrino](http://padrinorb.com) в качестве примера, предположим, что у вас есть модель `Post`, заполненная записями блога, вы можете отрисовать представление API (как JSON, так и XML) создав маршрут:```ruby
# app/app.rb
get "/posts", :provides => [:json, :xml] do
@user = current_user
@posts = Post.order("id DESC")
render "posts/index"
end
Затем мы можем создать следующий шаблон RABL для вывода API из @posts:```ruby
collection @posts attributes :id, :title, :subject child(:user) { attributes :full_name } node(:read) { |post| post.read_by?(@user) }
Что выведет следующий JSON или XML при посещении `http://localhost:3000/posts.json````js
[{ "post" :
{
"id" : 5, title: "...", subject: "...",
"user" : { full_name : "..." },
"read" : true
}
}]
Это базовый обзор, но есть гораздо больше, например, партиалы, наследование, пользовательские узлы и т.д. Полные детали RABL читайте ниже.
RABL предназначен для работы с минимальной или нулевой настройкой. Это верно для большинства сценариев, но в зависимости от ваших потребностей вы можете задать следующие глобальные конфигурации в вашем приложении (этот блок полностью опционален):```ruby
require 'rabl' Rabl.configure do |config|
end
Каждый параметр определяет поведение вывода RABL. Если `include_json_root` отключён, это удаляет корневой узел для каждого корневого объекта в выводе, а `enable_json_callbacks` включает поддержку 'jsonp'-подобного стиля обратного вызова, если входящий запрос содержит параметр 'callback'.
Если `include_child_root` установлен в false, дочерние объекты в ответе по умолчанию не будут включать корневой узел. Это позволяет дополнительно точно настроить желаемую структуру ответа.
Если задан `cache_engine`, ему следует присвоить класс с методом `fetch`. Смотрите [стандартный движок](https://github.com/nesquena/rabl/blob/master/lib/rabl/cache_engine.rb) в качестве примера.
Если `perform_caching` установлен в `true`, будет выполняться кеширование. Вы можете игнорировать этот параметр, если используете Rails, он аналогичен параметру Rails `config.action_controller.perform_caching`.
Если `cache_sources` установлен в `true`, поиск шаблонов будет кешироваться для повышения производительности. Кеш можно сбросить вручную, выполнив `Rabl.reset_source_cache!` в вашем приложении.
Если `cache_all_output` установлен в `true`, каждый шаблон, включая каждый отдельный шаблон, используемый как часть коллекции, будет кешироваться отдельно. Кроме того, всё внутри child, glue и partial также будет кешироваться отдельно. Чтобы кешировать только один шаблон, смотрите раздел «Кеширование» ниже.
Если `escape_all_output` установлен в `true` и ActiveSupport доступен, вывод атрибутов будет экранироваться с помощью [ERB::Util.html_escape](http://corelib.rubyonrails.org/classes/ERB/Util.html). Пользовательские узлы не будут экранироваться, используйте `ERB::Util.h(value)`.