【Rails】annotateの使い方

annotateとは

各モデルの情報をファイルの先頭もしくは末尾にコメントとして書き出してくれるGemのこと。
カラムを確認したい時にいちいちdb/schema.rb、db/migrateを見に行く手間を省けます。
加えて、config/routes.rbにルーティング情報を書き出してくれる機能もあります。
rails routesを実行して確認する手間が省けるので、なかなか利便性の高いgemです。

環境

・Mac M1 バージョン11.4
・Ruby 2.6.8
・Rails 6.1.4.1

annotateをインストール

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

Gemfile

gem 'annotate'

% bundle install

設定ファイルを作成

以下のコマンドを実行し、annotateの設定を色々と変えられるようにコマンド打ちます。

% bundle exec rails g annotate:install

lib/tasks/auto_annotate_models.rake

# NOTE: only doing this in development as some production environments (Heroku)
# NOTE: are sensitive to local FS writes, and besides -- it's just not proper
# NOTE: to have a dev-mode tool do its thing in production.
if Rails.env.development?
  require 'annotate'
  task :set_annotation_options do
    # You can override any of these by setting an environment variable of the
    # same name.
    Annotate.set_defaults(
      'active_admin'                => 'false',
      'additional_file_patterns'    => [],
      'routes'                      => 'false',
      'models'                      => 'true',
      'position_in_routes'          => 'before',
      'position_in_class'           => 'before',
      'position_in_test'            => 'before',
      'position_in_fixture'         => 'before',
      'position_in_factory'         => 'before',
      'position_in_serializer'      => 'before',
      'show_foreign_keys'           => 'true',
      'show_complete_foreign_keys'  => 'false',
      'show_indexes'                => 'true',
      'simple_indexes'              => 'false',
      'model_dir'                   => 'app/models',
      'root_dir'                    => '',
      'include_version'             => 'false'
---------------------------------------------------------------------

このように全てでは無いですが、設定ファイルが作成されます。
このファイルでannotateの設定を色々と変えることができます。

これでannotateの設定は完了です。

次にモデルの情報を入れてみます。

モデルの情報を記述する

以下のコマンドを実行します。

％ rails g model User name:string email:string age:integer

これでUserモデルに、「name」「email」「age」の情報を書き出すことができました。

準備は完了しました。
annotateを反映させていきます。
以下のコマンドを入力します。

% rails db:migrate

rails db:migrateを実行するとAnnotated (3): app/models/user.rb, ...というメッセージが表示され、自動的にファイルの先頭にスキーマ情報が書き出されます。

手動でannotateを実行する

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

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

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

書き換えたい時は再度

% bundle exec annotate --delete
% rails db:migrate

情報をファイルの末尾に出す場合

設定ファイル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' に変更します。

rubylib/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