JSON Hyper-SchemaからOpenAPI3に変換するスクリプトを作った

2018-11-02

JSON Hyper-SchemaからOpenAPI3に変換するスクリプトを作りました。一旦はOpenAPI3でエラーのない状態に変換できます。
https://github.com/ota42y/json_hyperscheme_to_openapi3

残念ながらこの２つの仕様には完全な互換性はありません。そのため、手元のJSON Hyper-Schemaデータに特化したいくつかの前提条件をおいています。他の環境下ではこの前提条件が崩れる可能性があり、その場合はうまく変換できないのでご留意ください。

なお、現状ではまだ変換したファイルを使い込んでいないため、今後よりきちんと変換機能を作り込んでいく可能性はあります。

Objectに関する制約事項

Path Item Objectへの自動変換

JSON Hyper-SchemaにはOpenAPI3のPath Item Objectは存在しません。そのため、Hyper-Schemaのobjectがhref属性を持つならば、それをPath Item Objectに対応するものとして変換します。また、それ以外に関してはすべてSchema Objectとみなし、comonents/schemas以下に配置します。なお、このときのリファレンス名はHyper-Schemaのidとプロパティ名から自動で生成します。

Nullableの自動付与

以下のように、Hyper-SchemaではanyOfを利用してnullableを表現できます。

"cursor": {
  "anyOf": [
    {
      "$ref": "#/definitions/v1_posts/definitions/cursor_id"
    },
    {
      "type": "null"
    }
  ]
},

OpenAPI3ではObjectにnullableを設定するようになったため、この表現はできません。そのため、変換時にanyOfの他のObjectに対してnullableを付与して回避しています。ただし、複数のところからreferenceされており、かつ場所によってnull/非nullになる場合、強制的にすべてnullableになりますのでご注意ください。

"non_null_cursor": {
  "$ref": "#/definitions/v1_posts/definitions/cursor_id"
},
"cursor": {
  "anyOf": [
    {
      "$ref": "#/definitions/v1_posts/definitions/cursor_id"
    },
    {
      "type": "null"
    }
  ]
}

このような場合、上では非null、下ではnullableですが変換すると対象のオブジェクトにnullable属性が付与されるため、どちらもnullableになります。

anyOf以外は未サポート

allOfとかは使ってなかったのでサポートしていません。

Path Item Objectに関する制約

同じhref属性を持つものは存在しない

JSON Hyper-Schemaは自由に定義を書けるため同じhrefに対して二重に定義できてしまいますが、OpenAPI3では定義できるhrefは一つのみになります。そのため、複数あった場合はエラーにしています。

レスポンスはapplication/jsonのみ

です

レスポンスボディは常にある

href属性を持ち、かつtargetSchemaがない場合にエラーになります。この場合は、空っぽのobjecを追加してください

パスパラメータを別途用意する

OpenAPI3ではパスパラメータの定義をしっかりと書かないといけませんが、JSON Hyper-Schemaでは書かなくても問題ありません。そのため、パスパラメータの情報が足りず、どうやっても変換できないため、以下のother_data.ymlにパスとパラメータの情報を追加する必要があります。

私の手元にあるファイルでは一応エラーのないOpenAPI3形式に変換はできました。
ただし、これを活用できるようにまだ整えられていないため、今後もう少し改良が入る可能性はあります。

追記

2019/03/31 リポジトリのURLが無かったので追加