committee 3.0とOpenAPI3対応方針

committee 3.0とOpenAPI3対応方針

RubyでOpenAPIやJSON Hyper-Schemaを使い、リクエスト・レスポンスバリデーションができるcommitteeのコミッターになりました。
また、同時にOpenAPI3対応を進めています。   https://github.com/interagent/committee/pull/145

方針としては以下のとおりです。

インターフェースに依存させるようにリファクタリング

現状のcommitteeはdefinitionの配列が存在するなど、JSON Hyper-Schema前提の作りになっています。既にあるOpenAPI2対応はそれに当てはまるようにデータを上手く変換して対応しています。OpenAPI3も同じように対応することを考えましたが、そうするとOpenAPI3の様々な良さを失ってしまいます。

そこで、一度スキーマを参照する部分を抽象化した操作にし、そのインタフェースに依存するようにリファクタリングします。具体的にはこのPRを見て頂くとわかります。
https://github.com/interagent/committee/pull/149/files

validationする際にJSON Hyper-Schemaを操作するのではなく、Schemaクラスのオブジェクトに対してvalidationを命じるという形になります。そして、JSON Hyper-SchemaとOpenAPI2がSchemaクラスの具体的な実装の一つとして実装します。最後に、新たなスキーマの一つとしてOpenAPI3対応を実装するイメージです。

Schemaクラスを使わない方法をdrop

上記の理由から、内部では全てSchemaクラスのオブジェクトに対して操作を行います。
既存のcommitteeではJSONやstringを渡すことでHyper-Schema用のオブジェクトを内部で生成していましたが、 OpenAPI3対応すると内部でどのクラスのオブジェクトを作れば良いか決定できなくなります。
もともと現在のcommitteeでもdeprecatedだったため、3.0系ではこれをdropし、きちんとどの種類のSchemaなのかを利用者側が指定する仕組みに変更します。  

具体的には以下のような使い方になります。

json = JSON.parse(File.read(...))
schema = Committee::Drivers::HyperSchema.new.parse(json)
use Committee::Middleware::RequestValidation, schema: schema

https://github.com/interagent/committee#set-committeedriversschema-object-for-middleware

そのため、committeeに対して一度リファクタリングや移行用の変更を含めた2.x系のバージョンを出していきます。 リファクタリング結果をベースにOpenAPI3対応をしていきますので、なにかしらバグ等があればご協力をお願いします。

将来的な展望

OpenAPI3を処理する部分をうまく切り離し、例えばよりRailsに特化したgemやmrubyで処理するgemなど、別のところにも流用が効くような形での実装を考えています。
将来的にはcommitteeはOpenAPI3でバリデートするgemを利用する一つのgemとして存在する…みたいな先を想定しています。

なお、これらはすべて現在の方針であり、容易に変更することをご留意ください。