web-dev-qa-db-fra.com

Comment référencer des exemples d'éléments de tableau dans OpenAPI 3?

En utilisant cette définition de schéma:

schemas:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      - id: 1
        firstName: Sherlock
        lastName: Holmes
      - id: 2
        firstName: John
        lastName: Watson

J'obtiens ce résultat attendu:

[
  {
     "id": 1,
     "firstName": "Sherlock",
     "lastName": "Holmes"
  },
  {
     "id": 2,
     "firstName": "John",
     "lastName": "Watson"
  }
]

Maintenant, je voudrais réutiliser l'exemple Holmes pour l'utilisateur unique (ContactModel1) et dans le cadre d'un tableau d'utilisateurs (AllContacts). Mais si j'utilise les exemples référencés:

schemas:

  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      Homes:
        $ref: '#/components/examples/Homes'
      Watson:
        $ref: '#/components/examples/Watson'

  examples:

    Holmes:
      value:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    Watson:
      value:
        id: 2
        first_name: John
        last_name: Watson

J'obtiens ce résultat inattendu dans Swagger UI:

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  },
  {
    "value": {
      "id": 2,
      "first_name": "John",
      "last_name": "Watson",
    },
    "$$ref": "#/components/examples/Watson"
  }
]

et un exemple similaire inattendu pour GET /user/1:

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  }
]

Qu'est-ce que je fais mal?

J'utilise ce document comme référence:
https://swagger.io/docs/specification/adding-examples/#reuse

swagger-uiopenapi
7
Old Man Walter

Ce n'est PAS une définition valide:

components:
  schemas:
    AllContacts:
      type: array
      items:
        $ref: '#/definitions/ContactModel1'
      example:
        Homes:
          $ref: '#/components/examples/Homes'
        Watson:
          $ref: '#/components/examples/Watson'

1) La syntaxe example est incorrecte. OpenAPI 3.0 a deux mots-clés pour les exemples - example (singulier) et examples (pluriel). Ils fonctionnent différemment:

  • example nécessite un exemple en ligne et ne prend pas en charge $ref.
  • examples est une carte (collection) d'exemples nommés. Elle supporte $ref - mais vous ne pouvez que $ref des exemples entiers, pas des parties individuelles d'un exemple . Cela signifie également qu'il n'est pas possible de créer un exemple à partir de plusieurs $refs. Notez que tous les éléments ne prennent pas en charge le pluriel examples.

Remarque pour les utilisateurs de Swagger UI: Swagger UI prend actuellement en charge example (singulier) mais pas examples (pluriel). La prise en charge de examples est suivie dans ce problème .

2) Le Schema Object ne supporte que le singulier example mais pas le pluriel examples. En d'autres termes, les schémas ne prennent en charge que les exemples en ligne .

3) Dans OpenAPI 3.0, les références de schéma utilisent le format #/components/schemas/..., ne pas #/definitions/...

Je voudrais utiliser la même définition d'EXEMPLE pour Holmes dans les deux cas, le tableau d'utilisateurs et l'utilisateur unique.

Il n'y a aucun moyen de réutiliser une partie d'un exemple dans ce cas. Vous devrez répéter l'exemple de valeur dans les deux schémas:

components:
  schemas:
    ContactModel1:
      type: object
      properties:
        ...
      example:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    AllContacts:
      type: array
      items:
        $ref: '#/components/schemas/ContactModel1'
      example:
        - id: 1
          first_name: Sherlock
          last_name: Holmes
        - id: 2
          first_name: John
          last_name: Watson
16
Helen