English | 日本語
OpenAPI のリクエスト schema と StructuredParams::Params クラスの差分を検出し、
片方だけが変更されて乖離することを防ぎます。
このドキュメントで component と呼ぶのは、OpenAPI ドキュメントの
components.schemas 配下にある、名前付きの schema のことです。各 Params クラスは、
名前で見つけた 1 つの component と照合されます(たとえば CreateUserParams →
CreateUser)。
# openapi.yml
components:
schemas:
CreateUser: # <- これが「component」(JSON Pointer は #/components/schemas/CreateUser)
type: object
properties:
name: { type: string }initializer を追加し、必要な部分だけ残してください。この例の OpenAPI ドキュメントは
TypeSpec から生成されているため、component 名は V1.Orders.CreateRequest のような形で、
クラス名は Api::V1::Orders::CreateRequestParameter のような形です。
# config/initializers/structured_params_openapi.rb
StructuredParams::OpenAPI.configure do |config|
# 必須: OpenAPI ドキュメントと、検査するクラス
config.document = Rails.root.join('docs/api/openapi.yaml').to_s
config.parameter_class_filter = ->(klass) { klass.name&.start_with?('Api::') }
# component 名が既定の規則(CreateUserParams -> CreateUser)と異なる場合だけ:
# Api::V1::Orders::CreateRequestParameter -> "V1.Orders.CreateRequest"
config.schema_name_resolver = lambda do |klass|
klass.name.delete_prefix('Api::').delete_suffix('Parameter').gsub('::', '.')
end
# schema があるはずだがまだないクラスがある場合だけ:
# 失敗にせず、記録だけ残す
%w[
Api::V1::Reports::ExportRequestParameter
Api::V1::Reports::SummaryRequestParameter
].each do |name|
config.ignore_drift(kind: :missing_schema, parameter_class: name)
end
end
# 上の規則に従わない component 名を持つクラスがある場合だけ
{
'Api::V1::Orders::KonbiniRequestParameter' => 'V1.Orders.CreateKonbiniRequest',
'Api::V1::Orders::BankTransferRequestParameter' => 'V1.Orders.CreateBankTransferRequest'
}.each do |parameter_class, schema|
StructuredParams::OpenAPI::Registry.register(parameter_class, schema: schema)
endparameter_class_filterは検査するクラスを選びます。新しいApi::*クラスは、登録なしで 対象になります。schema_name_resolverは、1 つの規則で全クラスを component に対応付けます。ignore_driftは、まだ schema がないクラスを記録します。Rake の出力には一覧表示され 続けます。検査する予定のないクラスは、filter から外すほうが適切です (対象範囲、skip、schema の欠落を参照)。Registry.registerは、命名の規則に合わない少数のクラスを個別に対応付けます。
あとは Rake タスクを実行すると、直すべき残りが分かります。
bundle exec rake structured_params:openapi:drift_check既定では、CreateUserParams を #/components/schemas/CreateUser に対応付けます。
クラスの namespace と、末尾の Param、Params、Parameter、Parameters、Form を
取り除いた名前が component 名になります。
component の命名規則が異なる場合は、schema_name_resolver で全体の規則を変更します。
たとえば OpenAPI 側で、Api::V1::CreateUserParams と Api::V2::CreateUserParams に
対応する component が V1CreateUserRequest と V2CreateUserRequest という名前の場合は、
次のようにします。
# openapi.yml
components:
schemas:
V1CreateUserRequest: # <- 既定の規則では CreateUser を探してしまう
type: object
properties:
name: { type: string }
V2CreateUserRequest: ...StructuredParams::OpenAPI.configure do |config|
config.schema_name_resolver = ->(parameter_class) do
# Api::V1::CreateUserParams -> "V1CreateUser" -> "V1CreateUserRequest"
name = parameter_class.name.delete_prefix('Api::').delete_suffix('Params').gsub('::', '')
"#{name}Request"
end
endresolver が返すのは component 名で、すべてのクラスで既定の規則の代わりに使われます。
この例が取り除くのは Params だけなので、CreateUserForm は CreateUserFormRequest
になります。
返す名前には namespace を残してください。残さない(たとえば demodulize で外す)と、
Api::V1::CreateUserParams も Api::V2::CreateUserParams も存在しない
CreateUserRequest を探してしまい、missing_schema になります。バージョンごとに
OpenAPI ファイル自体が分かれている場合は、component 名はそのままにして、
document_resolver でファイルを切り替えます
(複数の OpenAPI ファイルを参照)。
例外的なクラスには、schema: で component 名を渡します。JSON Pointer
('/components/schemas/CreateUserRequest'、'#/…')や、インラインの Hash も渡せます。
pointer: で Pointer を明示でき、openapi: で 1 回の呼び出しに限って設定済みの
ドキュメントを上書きできます(ファイルパスまたは Hash)。
StructuredParams::OpenAPI::DriftCheck.call(
parameter_class: CreateUserParams,
schema: 'CreateUserRequest'
)schema の type |
許容する attribute の型 |
|---|---|
string |
:string、:date、:datetime、:time(format は見ません) |
integer |
:integer、:big_integer |
number |
:float、:decimal |
boolean、object、array |
同じ型 |
type も properties もない schema(たとえば enum だけの schema)は、
type_mismatch として報告されます。ネストした object と array の型は再帰的に比較します。
schema の property は attribute 宣言と比較します。
schema の required は presence 検証と比較しますが、この対応は近似です。OpenAPI の
required が意味するのは「キーが存在すること」だけです。Rails では、キーが無い場合も値が
nil の場合も、属性は nil になります。そのため「キーが存在する」ことを表現できる
バリデータはなく、presence、allow_nil、allow_blank のどれが意図なのかも分かりません。
そこでこのチェックは、無条件の validates ..., presence: true を代わりの目安として使います
(「無条件」とは、if:、unless:、on:、allow_nil:、allow_blank: のいずれも指定されて
いないことです)。
schema が null を許す required の property(nullable: true、'null' を含む type 配列、
null を選択肢に持つ oneOf/anyOf)には、presence は不要です。presence を付けると、
契約が許している null を拒否してしまうため、報告されません。
これらのオプションが付いた presence は、キーが無くても通る可能性があるため、required
を満たすか確認できず、missing_presence_validation として報告されます。これは必ずしも
バグではありません。Ruby 側が意図的な書き方なら、
ignore_driftで property ごとに許容してください。presence
が API 全体にとって厳しすぎる場合(required が許す false や "" も拒否します)は、
required_validation: :none を指定し、必須キーの挙動は別に検証してください。
JSON の property 名と Ruby の attribute 名が異なる場合は property_names を使います。
StructuredParams::OpenAPI::DriftCheck.call(
parameter_class: CreateUserParams,
property_names: { user_id: 'userId' }
)結果をそのまま失敗メッセージに使うと、CI の失敗に検出した差分がすべて並びます。
it 'matches the request schema' do
result = StructuredParams::OpenAPI::DriftCheck.call(
parameter_class: CreateUserParams
)
expect(result).to be_valid, result.to_message
endrequired_validation: :none と Registry はクラス全体に作用するため、既知の 1 件だけを
許容して、同じパスの他の検査は続けたい場合には粗すぎます。その場合は ignore 規則を
設定します。
StructuredParams::OpenAPI.configure do |config|
config.ignore_drift(path: 'wallet_information.wallet_type', kind: :missing_presence_validation)
end- 規則は、そのパスが現れるすべての場所に適用されます。複数のトップレベルクラスが 再利用するネストした object では、親クラスごとに 1 回ずつ適用されます。
kind:を省略すると、そのパスのすべてのエラー種別を無視します。指定できる種別はmissing_attribute、unexpected_attribute、missing_presence_validation、type_mismatch、missing_schema、unresolved_referenceで、それ以外はArgumentErrorになります。parameter_class:(クラスまたはその名前)を渡すと、規則を 1 つのクラスに限定できます。- パスは attribute 名を
.でつなぎ、配列の要素には[]を付けます (例:items[].sku)。path:、kind:、parameter_class:はどれも規則を絞り込み、 省略したものは「すべて」に一致しますが、少なくとも 1 つは必要です。schema が見つからない 場合(missing_schema)は、property ではなくクラス全体についての指摘なので、path:を省略します。 - skip は無視できません。
無視した検出結果は result.errors ではなく result.ignored に移ります。そのため
valid? は解決済みとして扱い、to_message にも表示されません。ただし結果オブジェクト
には残るので、何をなぜ抑制しているかを後から確認でき、黙って消えることはありません。
gem は Rails アプリケーションに structured_params:openapi:drift_check を提供します。
このタスクは parameter_class_filter で選択されたクラスを自動で検査するため、新しい
Api::*Params クラスに登録は不要です。
- filter がなければ登録済みのクラスだけが対象で、何も検査されなかった場合は タスクが警告します。
- 無名クラスは自動検出されません。filter の例が
name&.で守られているのはそのためです。
Registry は、例外的な component 名や property の対応付けが必要な場合にだけ使って ください。同じクラスに対しては、明示的な登録が自動検出より優先されます。同じクラスを 後から登録すると、先の登録を置き換えます。
StructuredParams::OpenAPI::Registry.register(
LegacyUserParams,
schema: 'LegacyCreateUserRequest'
)parameter_class にはクラス名の文字列も渡せます。この場合はタスクの実行時に解決
されます。Rails の autoload がまだ設定されていない config/initializers/*.rb から
登録するときに便利です。クラス定数を直接参照すると NameError になるためです。
StructuredParams::OpenAPI::Registry.register(
'LegacyUserParams',
schema: 'LegacyCreateUserRequest'
)アプリケーションに複数の OpenAPI ファイルがある場合(たとえば admin_api.yml と
front_api.yml)は、document_resolver を設定すると、自動検出された各クラスを
それぞれのファイルに対して検査できます。nil を返したクラスは config.document に
フォールバックします。
StructuredParams::OpenAPI.configure do |config|
config.parameter_class_filter = ->(klass) { klass.name&.match?(/\A(AdminApi|FrontApi)::/) }
config.document_resolver = ->(klass) do
case klass.name
when /\AAdminApi::/ then Rails.root.join('openapi/admin_api.yml').to_s
when /\AFrontApi::/ then Rails.root.join('openapi/front_api.yml').to_s
end
end
end個別のクラスには Registry.register(..., openapi:)(ファイルパスまたは Hash)で
resolver を上書きできます。どちらもなければ、設定済みの document を使います。
StructuredParams::OpenAPI::Registry.register(
AdminUserParams,
openapi: Rails.root.join('openapi/admin.yml').to_s
)bundle exec rake structured_params:openapi:drift_checkskip も失敗扱いにしたい場合は、STRUCTURED_PARAMS_STRICT=1 を設定します(下記参照)。
通常の schema と同じように扱うもの:
- OpenAPI 3.1 の nullable の書き方:
{type: null}を選択肢に持つoneOf/anyOfと、'null'を含むtype配列(たとえば[string, 'null'])。null の選択肢を除くと、 3.0 のnullable: trueと同じように比較されます。 - スカラーだけの
oneOf/anyOf(たとえばstringかinteger)。attribute がどれか 1 つの 選択肢に合えば一致します。 - 要素が 1 つだけの
allOf。TypeSpec が$refにdescriptionを付けるときに出力する形です。
現在の対象範囲では、次のものを意図的に skip します。
- object の
oneOf/anyOf、複数要素のallOf - null 以外の型を複数持つ
type配列 - 外部参照
再帰する schema は、祖先の連鎖ごとに 1 回だけ比較され、繰り返しの訪問は黙って打ち切られます。
skip は実行を失敗させませんが、黙ってもいません。Rake タスクは skip と ignore の
すべての項目をサマリ行とともに表示し、RSpec では result.skipped と
result.to_report で確認できます。skip も失敗扱いにしたい場合は、
STRUCTURED_PARAMS_STRICT=1 を設定するか、Registry.check_all! に strict: true を
渡してください。
解決した schema 名に対応する component がないクラスは、missing_schema エラーとして
報告されます。壊れた、または循環するローカルの $ref も同様です
(unresolved_reference)。component 名の変更や打ち間違いで、検査が黙って外れること
はありません。意図的に schema を持たないクラス(たとえば query parameter が元の
クラス)は、次の 2 通りで扱えます。
-
検査する予定がないなら、
parameter_class_filterから外します。そのクラスはまったく 検査されず、記録も残りません。NO_SCHEMA = %w[Api::V1::SearchParams].freeze StructuredParams::OpenAPI.configure do |config| config.parameter_class_filter = ->(klass) do klass.name&.start_with?('Api::') && NO_SCHEMA.exclude?(klass.name) end end
-
本来は schema があるはずだが、まだない場合は、そのクラスの指摘を無視します。指摘は
result.ignoredに移り、Rake タスクにも一覧表示されるので、後から見直せます。StructuredParams::OpenAPI.configure do |config| config.ignore_drift(kind: :missing_schema, parameter_class: 'Api::V1::SearchParams') end
result.to_message の先頭には検査したクラス名が付くため、check_all! がまとめて
投げる DriftError のメッセージは、パスをただ並べたものではなく、クラスごとの
ブロックになります。