先生と生徒の会話形式で理解しよう

生徒

「RailsでAPIを作るときに、JSONの形を整える方法ってありますか？」

先生

「Railsでは、Jbuilderというテンプレートを使うことで、JSONを自由に整形できますよ。」

生徒

「テンプレートでJSONを整えるってどういうことですか？HTMLみたいに作れるんですか？」

先生

「そうなんです。ERBでHTMLを生成するように、JbuilderでJSONを生成できるんです。では詳しく説明しましょう。」

1. RailsでJSONを扱う理由とは？

RailsでAPIを作るとき、多くの場合は外部サービスやフロントエンドアプリケーションと情報を交換します。そのときによく使われる形式がJSONです。JSONは人間が読めて機械も扱いやすいデータ形式で、インターネット上のコミュニケーションに広く利用されています。RailsはこのJSONを生成する仕組みを標準で備えており、特にAPI構築では欠かせない技術になります。

2. JSONとは何かを初心者向けにイメージしよう

JSONは簡単に言うと、情報をきれいに箱に入れて整理したものです。例えば「ユーザー」という情報を保存するなら、名前や年齢といった項目を箱にまとめて、相手に渡すイメージです。Railsではこれを自動的に作ったり、自由に形を整えることができます。特に大規模なアプリでは、一定のルールでJSONを整形することが重要で、そのためにJbuilderが活躍します。

3. Jbuilderとは何？テンプレートでJSONを作る仕組み

Jbuilderとは、Rubyのコードを使ってJSONを組み立てるためのテンプレートエンジンです。ERBがHTMLテンプレートを作るように、JbuilderはJSONテンプレートを作ります。

Jbuilderを使うことで、コントローラの中で複雑なJSONをベタ書きする必要がなくなり、テンプレートとして整理された状態で管理できます。これにより、Rails全体の設計が見やすくなり、保守性が高まります。

Jbuilderファイルの基本例


# app/views/users/show.json.jbuilder
json.id @user.id
json.name @user.name
json.email @user.email

このように、Rubyのメソッド形式で項目を追加していきます。書いた順番がそのままJSONの構造になります。

4. JbuilderでネストしたJSONを作る方法

初心者がつまずきやすいのがネスト構造です。ネストとは「箱の中にさらに箱を入れる」イメージで、複雑なデータを整理するために必要です。


json.user do
  json.id @user.id
  json.profile do
    json.age @user.age
    json.city @user.city
  end
end

この書き方により、ユーザー情報の中にプロフィール情報を入れる、といった柔軟な構造が作れます。APIではよく使う書き方なので覚えておくと便利です。

5. 配列（リスト）をJSONにする方法

商品一覧やユーザー一覧など、複数のデータを一度に返すAPIも多くあります。Jbuilderでは配列を次のように表現します。


json.array! @users do |user|
  json.id user.id
  json.name user.name
end

このようにループを活用することで、一覧表示のJSONを簡単に整形できます。

6. Builderとは？XMLを扱うテンプレートとの違い

RailsにはJSON用のJbuilderとは別に、Builderというテンプレートもあります。これはXMLを生成するためのテンプレートで、構造としてはJbuilderと似た書き方をします。現在はJSONの方が一般的ですが、古いシステムでXMLを扱う場面もあるため、BuilderもRailsに標準で含まれています。