web-dev-qa-db-fra.com

Définir un tableau de plusieurs modèles dans Swagger 2.0

C'est ma première incursion dans Swagger, alors s'il vous plaît soyez doux.

J'ai les définitions suivantes:

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          $ref: '#/definitions/Indicator'
  Indicator:
    type: object
    properties:
      type:
        type: string
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
  BBANDS:
    properties:
      type:
        type: string
        default: BBANDS
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
        properties:
          timeperiod:
            type: integer
            format: int32
            default: 5
          nbdevup:
            type: integer
            format: int32
            default: 2
          nbdevdn:
            type: integer
            format: int32
            default: 2
          matype:
            type: integer
            format: int32
            default: 0
  DEMA:
    properties:
      type:
        type: string
        default: DEMA
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
        properties:
          timeperiod:
            type: integer
            format: int32
            default: 5

Donc Payload a une propriété appelée indicator qui est un tableau de Indicators. BBANDS et DEMA sont des modèles de type Indicator (que je ne connais pas) t traduire en Swagger). Ce que j'aimerais faire, c'est définir un tableau des modèles réels avec leurs valeurs par défaut, dans ce cas BBANDS et DEMA. Quelque chose comme ça:

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          - '#/definitions/BBANDS'
          - '#/definitions/DEMA'

ou

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          - $ref '#/definitions/BBANDS'
          - $ref '#/definitions/DEMA'

Aucun des deux ne fonctionne bien sûr. La raison en est que tandis que le modèle Indicator décrit correctement un indicator, différents indicator peuvent avoir un jeu de paramètres différent.

Existe-t-il un moyen de définir essentiellement une liste de plusieurs modèles ou peut-être de mapper les modèles BBANDS et DEMA dans Indicator?

Edit: résultat de l'utilisation de la première suggestion de @ Helen dans l'éditeur Swagger

enter image description here

swaggerswagger-2.0
13
Jason Strimpel

Swagger/OpenAPI 2.0 ne prend pas en charge plusieurs types pour items, mais il existe plusieurs façons de décrire ce dont vous avez besoin.

Option 1 - Héritage du modèle

Tant que vous avez un champ commun aux modèles et que vous pouvez utiliser pour les distinguer, vous pouvez utiliser l'héritage de modèle:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaDiscriminatorhttps://github.com/OAI/OpenAPI-Specification/ blob/master/versions/2.0.md # polymorphisme de composition et d'héritage

Dans votre exemple, cette propriété est type (type="BBANDS" ou type="DEMA"). Afin que vous puissiez:

  • Héritez les modèles BBANDS et DEMA de Indicator en utilisant allOf.
  • Ajouter discriminator: type à Indicator pour indiquer que la propriété type sera utilisée pour distinguer les sous-modèles.
  • Définissez Payload comme un tableau de Indicator. De cette façon, il peut s'agir en fait d'un tableau de BBANDS ou d'un tableau de DEMA.
definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          $ref: '#/definitions/Indicator'

  Indicator:
    type: object
    properties:
      type:
        type: string
        # Limit the possible values if needed
        #enum:
        #  - BBANDS
        #  - DEMA
      computeOn:
        type: array
        items:
          type: string
        default:
          - close

    # The "type" property will be used to distinguish between the sub-models.
    # The value of the "type" property MUST be the schema name, that is, "BBANDS" or "DEMA".
    # (Or in other words, the sub-model schema names must match possible values of "type".)
    discriminator: type
    required:
      - type

  BBANDS:
    allOf:
      - $ref: '#/definitions/Indicator'
      - type: object
        properties:
          parameters:
            type: object
            properties:
              timeperiod:
                type: integer
                format: int32
                default: 5
              nbdevup:
                type: integer
                format: int32
                default: 2
              nbdevdn:
                type: integer
                format: int32
                default: 2
              matype:
                type: integer
                format: int32
                default: 0
  DEMA:
    allOf:
      - $ref: '#/definitions/Indicator'
      - type: object
        properties:
          parameters:
            type: object
            properties:
              timeperiod:
                type: integer
                format: int32
                default: 5

Option 2 - Modèle unique

Si tous les parameters sont des entiers, vous pouvez avoir un seul modèle Indicator avec parameters défini comme une table de hachage. Mais dans ce cas, vous perdez la possibilité de définir le parameters exact pour des types d'indicateurs spécifiques.

definitions:
  Indicator:
    type: object
    properties:
      type:
        type: string
        enum:
          - BBANDS
          - DEMA
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
        properties:
          # This is a common parameter in both BBANDS and DEMA
          timeperiod:
            type: integer
            format: int32
            default: 5
        # This will match additional parameters "nbdevup", "nbdevdn", "matype" in BBANDS
        additionalProperties:
          type: integer
9
Helen