OpenAPI では rails のクエリパラメータの完全サポートはできない

旧 swagger こと OpenAPI は、 api サーバーの仕様をプログラムで処理可能な形で記述できるツールであるが、特にクエリパラメータについては、 rails がサポートする形式の完全サポートは、仕様としてできていなかったので、それについての備忘録。

Rails のクエリパラメータのエンコード方法のおさらい

Action Controller の概要 - Railsガイド

本ガイドでは、コントローラの動作と、アプリケーションのリクエストサイクルでコントローラがどのように使われるかについて説明します。セッション、フィルタ、cookie、データストリーミング、リクエストによって発生する例外、その他多くの話題を取り扱っています。

railsguides.jp

Rails においては、クエリパラメータでオブジェクトや配列を指定したい場合、以下のように指定をする。

// 配列の場合
GET /foo?array_name[]=elem0&array_name[]=elem1
// オブジェクトの場合
GET /foo?obj_name[attr_name1]=attr1&obj_name[attr_name2]=attr2

// オブジェクトの配列
GET /foo?array_name[][attr_name1]=attr0_1&array_name[][attr_name2]=attr0_2&array_name[][attr_name1]=attr1_1&array_name[][attr_name2]=attr1_2

上記の通り、オブジェクトや配列の指定はネストできる。

OpenAPI でのクエリパラメータのオブジェクトなどのエンコード方式

OpenAPI では、クエリパラメータに対して object や array をその schema に指定したい場合、どのようにそれをクエリパラメータ上で表現するべきかについて、例えば下記のように、主に style で指定することになる。

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

OpenAPI specificationの parameter object のセクションより抜粋。

そして、上記の Open style による指定の一覧を見ていてわかるのは、

• array (配列) については、これを rails の方式で encode する方法はない。
• object については、 style: deepObject とすることで、 rails っぽくはなる。
  • ただし、ネストした object はサポートしない。 (ソース: https://github.com/swagger-api/swagger-js/pull/1450 )

まとめ

rails でクエリパラメータに複合型(array や object)を想定する場合において、 OpenAPI で表現ができるのは、ネストされないオブジェクトのみ。

ただし、ここで OpenAPI が仕様としてクエリパラメータでの object の表現方法を定めているからと言って、それが実際に OpenAPI 関連のツールでサポートされているかは別問題ではあったりする。