tool - swagger ui

“Discriminador” en el polimorfismo, OpenAPI 2.0(Swagger 2.0)

Question

Haciendo referencia a OpenAPI 2.0, Schema Object o Swagger 2.0, Schema Object , y la definición de campo discriminator como:

Agrega soporte para el polimorfismo. El discriminador es el nombre de la propiedad del esquema que se utiliza para diferenciar entre otros esquemas que heredan este esquema. El nombre de la propiedad utilizada DEBE estar definido en este esquema y DEBE estar en la lista de propiedades required . Cuando se utiliza, el valor DEBE ser el nombre de este esquema o cualquier esquema que lo herede.

Mis confusiones / preguntas:

• Es ambiguo para mí, qué papel juega exactamente en la herencia o el polimorfismo. ¿Podría alguien explicar el discriminator con un ejemplo práctico que muestre lo que hace exactamente y si no lo usamos? ¿Algún error, advertencia o alguna herramienta que dependa de él para algunas operaciones?
• ¿Es el caso que swagger-editor no soporta discriminator , y este campo se usa en algunas otras herramientas?

Lo que he intentado hasta ahora:

• He intentado usar swagger-editor y el ejemplo de la misma documentación (también se menciona a continuación), para jugar con esta propiedad para ver si puedo ver alguno de sus comportamientos especiales. Cambié la propiedad, la eliminé y extendí el modelo Dog a un nivel más profundo y probé lo mismo en el nuevo submodelo, pero no vi ningún cambio en la vista previa de swagger-editor .
• Intenté buscar en línea y, especialmente, las preguntas de stackoverflow, pero no encontré ninguna información relevante.

El código de muestra que solía hacer experimentos:

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

Answer 1

De acuerdo con este grupo de Google , el discriminator se utiliza en la parte superior de la propiedad allOf y se define en el allOf para polimorfismo. Si no se utiliza el discriminator , la palabra clave allOf describe que un modelo contiene las propiedades de otros modelos para la composición.

Al igual que en su código de muestra, Pet es un tipo super con propiedad de petType identificado como discriminator y Cat es un subtipo de Pet . A continuación se muestra un ejemplo json de un objeto Cat :

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

El uso del discriminator pretende indicar la propiedad utilizada para identificar el tipo de un objeto. Supone que hay herramientas que pueden admitir correctamente los objetos de definición con el uso del discriminator , es posible determinar el tipo escaneando la propiedad. Por ejemplo, identificar el objeto es un Cat según petType .

Sin embargo, el campo discriminator no está bien definido en la especificación de la versión actual o en las muestras (ver problema # 403 ). Hasta donde sé, no hay herramientas proporcionadas por Swagger que lo respalden adecuadamente en este momento.

Se puede usar un discriminator si el modelo tiene una propiedad utilizada para determinar el tipo. En este caso, es natural y se puede utilizar como un indicador para que otros desarrolladores entiendan la relación de polimorfismo. Si se consideran herramientas de terceros como ReDoc que admiten el discriminator (vea petType en este gif y example ), puede encontrar esto útil.

Answer 2

La funcionalidad del discriminador se ha mejorado mucho en OpenApi 3. Ahora proporciona un objeto discriminador que contiene el nombre de la propiedad discriminadora, así como una asignación de los valores de esa propiedad a los nombres de esquema.

(Me doy cuenta de que sí preguntaste sobre OpenApi 2, pero esto se ha mejorado tanto en 3 que espero que puedas utilizarlo).

Consulte: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject para la especificación real