`annotate`とは

各モデルのスキーマ情報をファイルの先頭もしくは末尾にコメントとして書き出してくれるGemです。
どんなカラムがあったっけ？ってなった時にいちいちdb/schema.rbを見に行く手間を省けます。
さらに、config/routes.rbにルーティング情報を書き出してくれる機能もあります。
いちいちrails routesを実行して確認する手間が省けますね。ありがたい。

環境

Rails 5.2.3
Ruby 2.6.3
annotate 2.7.5

準備

Gemfileに以下を記述して、bundle install。

Gemfile

gem 'annotate'

$ bundle install

設定ファイルを作成

以下のコマンドを実行するとlib/tasks/auto_annotate_models.rakeが作成されます。
このファイルで設定を色々変えられます。

$ bundle exec rails g annotate:install

モデルのスキーマ情報を書き出す

ここまでで既に基本的な機能は有効になっています。
試しにモデルを作成してみます。

$ rails g model User name:string email:string age:integer
$ rails db:migrate

rails db:migrateを実行するとAnnotated (3): app/models/user.rb, ...というメッセージが表示され、自動的にファイルの先頭にスキーマ情報が書き出されます。
カラムを新しく追加した時や、変更した時などもちゃんと書き出してくれます。

app/models/user.rb

# == Schema Information 
#
# Table name: users
#
#  id         :integer          not null, primary key
#  age        :integer
#  email      :string
#  name       :string
#  created_at :datetime         not null
#  updated_at :datetime         not null
#

class User < ApplicationRecord
end

便利！

手動でannotateを実行する

手動で実行したい場合は以下のコマンドを実行するだけで大丈夫です。

$ bundle exec annotate
$ bundle exec annotate --routes # ルーティング情報(後述)を書き出す
$ bundle exec annotate --exclude fixtures # fixturesには書き出さない
$ bundle exec annotate --exclude tests,fixtures,factories,serializers # modelファイルのみに書き出す

書き出されたコメントを削除する

annotateによって書き出されたコメントを削除したい場合は以下のコマンドを実行すればコメントが削除されます。

$ bundle exec annotate --delete
$ bundle exec annotate --routes --delete # ルーティング情報(後述)を削除する

スキーマ情報をファイルの末尾に書き出してほしい場合

設定ファイルの position_in_class を 'after' に変更します。

lib/tasks/auto_annotate_models.rake

- 'position_in_class' => 'before'
+ 'position_in_class' => 'after'

こうすればファイルの先頭ではなく末尾にスキーマ情報が書き出されるようになります。

`rails db:migrate`の時に勝手にコメントを書いて欲しくない場合

設定ファイルの skip_on_db_migrate を 'true' に変更します。

lib/tasks/auto_annotate_models.rake

- 'skip_on_db_migrate' => 'false'
+ 'skip_on_db_migrate' => 'true'

こうすればrails db:migrateを実行しても自動でスキーマ情報が書き出されなくなります。
また、設定を変更しなくても実行時にANNOTATE_SKIP_ON_DB_MIGRATEを設定すれば自動で書き出されません。

$ ANNOTATE_SKIP_ON_DB_MIGRATE=1 rails db:migrate

ルーティング情報を書き出す

実はannotateはモデルのスキーマ情報だけでなく、config/routes.rbにルーティング情報も書き出してくれます。
ルーティング情報を書き出してほしい場合は以下のコマンドを実行します。

$ bundle exec annotate --routes

config/routes.rb

# == Route Map
#
#                    Prefix Verb URI Pattern                                                                              Controller#Action
#        rails_service_blob GET  /rails/active_storage/blobs/:signed_id/*filename(.:format)                               active_storage/blobs#show
# rails_blob_representation GET  /rails/active_storage/representations/:signed_blob_id/:variation_key/*filename(.:format) active_storage/representations#show
#        rails_disk_service GET  /rails/active_storage/disk/:encoded_key/*filename(.:format)                              active_storage/disk#show
# update_rails_disk_service PUT  /rails/active_storage/disk/:encoded_token(.:format)                                      active_storage/disk#update
#      rails_direct_uploads POST /rails/active_storage/direct_uploads(.:format)                                           active_storage/direct_uploads#create

Rails.application.routes.draw do
  # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html
end

まとめ

便利。
間違っている箇所などありましたらご指摘お願いします。

参考

公式リポジトリ

【Rails】annotateの使い方

annotateとは

環境

準備