openapi_parser 0.3.1がでました

2019-06-12

openapi_parserの0.3.1が出ました。

主に以下の二つの機能が追加されています。

部分的なadditionalPropertiesのサポート
discriminatorのサポート

部分的なadditionalPropertiesのサポート

OpenAPI 3ではSchema ObjectにadditionalPropertiesという項目を設定できます。これはBoolean値もしくはSchema Objectを値として持つことができます。この値がfalseの場合はそのSchema Objectのpropertiesに設定された要素しか持てず、それ以外の要素があったらバリデーションは失敗します。 Schema Objectを設定した場合は、propertiesに設定されていない要素が全てadditionalPropertiesに設定されたSchemaと一致しなければなりません。 trueの場合はpropertiesに設定されていない要素に対してバリデーションを行わず、常に成功として返します(未指定の場合はtrueになります)。これはJSON Schema Validationで定義されている物のサブセットとなっています。

例えば以下のような定義だった場合、name以外の要素は全てintegerでなければなりません。

schema:
  type: object
  properties:
    name:
      type: string
  additionalProperties:
    type: integer

また、以下のように書くとname以外の要素は一切持てなくなります。

schema:
  type: object
  properties:
    name:
      type: string
  additionalProperties: false

今回の対応では後者のfalseのみをサポートし、まだSchema Objectの対応は行っていません。

discriminatorのサポート

oneOfや、anyOf、allOfを使うと、1つのSchema Objectで複数の定義を表現できます。

例えば以下の定義は、Cat/Doc/Lizardのどれか1つのみと一致する要素であるという意味になります。

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'

oneOfをanyOfに変えると、3つのうちどれか1つ以上と一致していればバリデーションが成功するようになるため、2つ、3つと一致しても大丈夫になります。

このとき、何もヒントが無い場合はチェック処理が重くなる可能性があります。そこで、パラメータにどの名前のSchema Objectであるかといったヒントを指定することができ、マッチ処理の高速化が行えます。以下のようにdiscriminatorのpropertyNameに指定した名前のプロパティにSchema Objectの名前を指定できるようになります。

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType

この定義には、以下のように要素がCatであるというヒントを送ることが出来ます。

{
  "id": 12345,
  "petType": "Cat"
}

また、propertyNameのマッピングを定義すると、指定する名前を自由に変更できます。例えば以下のように定義すると、petTypeにDogではなくinuでもDogを指定できるようになります。

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType
    mapping:
      inu: '#/components/schemas/Dog'

openapi_parserのバリデーション機能は今回これに対応したので、これらを多用している人には便利に使えると思います。