web-dev-qa-db-ja.com

ポリモーフィズムの「差別者」、OpenAPI 2.0（Swagger 2.0）

OpenAPI 2.0、スキーマオブジェクト 、または Swagger 2.0、スキーマオブジェクト の参照、およびdiscriminatorフィールドの定義：

ポリモーフィズムのサポートを追加します。識別子は、このスキーマを継承する他のスキーマを区別するために使用されるスキーマプロパティ名です。使用するプロパティ名はこのスキーマで定義する必要があり、requiredプロパティリストになければなりません。使用する場合、値はこのスキーマまたはそれを継承するスキーマの名前でなければなりません。

私の混乱/質問：

  • 継承やポリモーフィズムで正確にどのような役割を果たすかは、私にはあいまいです。誰かがdiscriminatorを説明し、それが正確に何をするのか、それを使用しない場合はどうなるのかを示す実例で説明してもらえますか？エラー、警告、または操作に依存するツールはありますか？
  • swagger-editor はdiscriminatorをサポートせず、このフィールドは他のいくつかのツールで使用されていますか？

私がこれまでに試したこと：

  • swagger-editor と同じドキュメントのサンプル（以下でも説明します）を使用して、このプロパティを操作して、その特別な動作を確認できるかどうかを確認しました。プロパティを変更して削除し、Dogモデルを1レベル深く拡張し、新しいサブモデルで同じことを試みましたが、 swagger-エディター 。
  • オンラインで検索し、特にstackoverflowの質問を試みましたが、関連する情報は見つかりませんでした。

実験に使用したサンプルコード：

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize
swaggerswagger-2.0swagger-editoropenapiswagger-tools
22
Musa

これによると、 google group 、discriminatorはallOfプロパティの上で使用され、ポリモーフィズムのスーパータイプで定義されます。 discriminatorが使用されていない場合、allOfキーワードは、モデルに構成用の他のモデルのプロパティが含まれていることを示します。

サンプルコードと同じように、PetはpetTypeのプロパティがdiscriminatorとして識別されるスーパータイプであり、CatはPet。以下は、Catオブジェクトのjsonの例です。

{
  "petType": "Cat",
  "name": "‎Kitty"
}

discriminatorの使用は、オブジェクトのタイプを識別するために使用されるプロパティを示すことを意図しています。 discriminatorを使用して定義オブジェクトを適切にサポートできるツールがあると仮定すると、プロパティをスキャンすることでタイプを判別できます。たとえば、Catに従ってオブジェクトがpetTypeであることを識別します。

ただし、discriminatorフィールドは、現在のバージョンの仕様またはサンプルで十分に定義されていません（ issue＃4 を参照）。私の知る限り、現時点ではSwaggerが適切にサポートしているツールはありません。

モデルにタイプを決定するために使用されるプロパティがある場合、discriminatorを使用できます。この場合、自然に適合し、他の開発者が多型関係を理解するための指標として使用できます。 ReDoc のようなdiscriminatorをサポートするサードパーティツール（この gif および example のpetTypeを参照）が考えてみると、これは役に立つかもしれません。

10
Wilson

OpenApi 3では弁別器の機能が大幅に改善されました。弁別器プロパティの名前を含む弁別器オブジェクトと、そのプロパティの値のスキーマ名へのマッピングを提供するようになりました。

（OpenApi 2について尋ねたことがありますが、これは3で大幅に改善されているので、うまく利用できれば幸いです）。

参照： https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject 実際の仕様について

5
natke