web-dev-qa-db-fra.com

Modèle de réponse complexe Swagger avec cartes de hachage dynamiques de valeurs clés

Je me bats avec la syntaxe de swagger pour décrire un type de réponse. Ce que je tente de modéliser est une carte de hachage avec des clés et des valeurs dynamiques. Ceci est nécessaire pour permettre une localisation. Les langues peuvent varier, mais l'anglais doit toujours être fourni.

La réponse ressemblerait à ceci dans JSON:

{
  id: "1234",
  name: {
    en: "english text",
    de: "Deutscher Text"
  }
}

Mon premier essai ressemblait à cela, mais je ne sais pas comment écrire la partie pour le nom. AdditionalProperties semble être une clé, mais je ne parviens pas à comprendre. Aussi, l'exigence de texte anglais est un mystère pour moi dans cette syntaxe et l'exemple ne semble pas non plus fonctionner comme prévu. Il génère un $ plié vide: dans l'interface utilisateur.

delayReason:
  type: object
  properties:
    id:
      type: string
      description: Identifier for a delay reason.
    name:
      type: object
      additionalProperties: 
        type: string
  required: [id, name]
  example:
    id: 123
    name: 
      en: english text
      de: Deutscher Text

Mais cela produit:  swagger editor result

Il n'y a pas non plus d'indice en ce que le résultat aura un code de langue en tant que clé et le texte en tant que valeur de la carte de hachage.

hashmapswaggerswagger-2.0swagger-editor
12
user1736217

Il semble que vous rencontriez au moins trois bogues et/ou limitations distincts:

  1. Ni Swagger-Editor ni Swagger-UI ne fournissent d'indication dans le format de la documentation indiquant que additionalProperties sont autorisés dans votre schéma d'objet. Ainsi, même si vous avez utilisé additionalProperties correctement et qu'il est reconnu par l'analyseur Swagger, ces formats de documentation ne l'afficheront pas. Vous devez ajouter ces détails à votre schéma description pour que les utilisateurs sachent qu'ils peuvent inclure des propriétés de chaîne supplémentaires.

    Remarque: Vous vous attendez probablement aussi à ce que les noms de propriété supplémentaires suivent une convention, par exemple. un code de langue à deux lettres. Bien que le schéma JSON complet vous permette de spécifier ceci avec patternProperties, ce n'est malheureusement pas pris en charge dans l'objet de schéma de Swagger. Encore une fois, vous devriez spécifier cela dans votre description de schéma.

  2. Le format Swagger-Editor affiche parfois cette propriété étrange "folded:". Je l'ai vu ce matin, étrangement je ne peux pas le reproduire. Il a peut-être été corrigé à chaud aujourd'hui. Quoi qu'il en soit, il s'agit certainement d'un bogue spécifique à Swagger-Editor. Cela ne devrait pas affecter votre génération de code en aval, ni l'interface standard Swagger-UI qui présente la documentation de votre API aux développeurs clients lors de l'exécution. (Bien que le volet de documentation de Swagger-Editor ressemble à celui de Swagger-UI, il s'agit d'une implémentation séparée.)

  3. Il existe certaines limitations subtiles mais importantes à l’utilisation de additionalProperties dans Swagger. Bien que l'exemple de Helen ne montre aucune erreur visible, l'analyseur Swagger ne traitera pas correctement ce schéma; il ignorera soit votre propriété en explicitement déclarée, soit additionalProperties! 

Ce dernier problème est lié à un défaut de conception dans Swagger-Model, l'un des composants principaux utilisés dans l'ensemble de la pile Java de Swagger (y compris Swagger-Codegen). Les schémas définis dans certains contextes peuvent fonctionner avec une combinaison de properties et additionalProperties. Mais les schémas définis dans d'autres contextes ne le peuvent pas. 

Nous avons documenté cela en détail ici .

La bonne nouvelle: avec un petit Tweak, nous pouvons faire en sorte que l'exemple d'Helen fonctionne correctement. Nous devons simplement extraire le schéma d'objet imbriqué dans sa propre définition de niveau supérieur. Je l'appellerai LocalizedName:

definitions:
  delayReason:
    type: object
    properties:
      id:
        type: string
        description: Identifier for a delay reason.
      name:
        $ref: "#/definitions/LocalizedName"
    required: [id, name]
    example:
      id: '123' # Note the quotes to force the value as a string
      name: 
        en: English text
        de: Deutscher Text

  LocalizedName:
    type: object
    description: A hashmap with language code as a key and the text as the value.
    properties:
      en:
        type: string
        description: English text of a delay reason.
    required: [en]
    additionalProperties: 
      type: string
12
Ted Epstein

Votre utilisation de additionalProperties est correcte et votre modèle est correct.

des propriétés supplémentaires

Dans Swagger/OpenAPI, les clés de hachage sont supposées être des chaînes, de sorte que le type de clé n'est pas défini explicitement. additionalProperties définir le type de valeurs hashmap. Donc, ce schéma

type: object
additionalProperties: 
  type: string

définit un mappage chaîne à chaîne tel que:

{
  "en": "English text",
  "de": "Deutscher Text"
}

Si vous aviez besoin d'une mappe chaîne/entier telle que:

{
  "en": 5,
  "de": 3
}

vous définiriez additionalProperties comme ayant le type de valeur integer:

type: object
additionalProperties: 
  type: integer

Clé requise dans un hashmap

Pour définir en en tant que clé requise dans la table de hachage:

type: object
properties:
  en:
    type: string
required: [en]
additionalProperties: 
  type: string

Exemple complet

definitions:
  delayReason:
    type: object
    properties:
      id:
        type: string
        description: Identifier for a delay reason.
      name:
        type: object
        description: A hashmap with language code as a key and the text as the value.
        properties:
          en:
            type: string
            description: English text of a delay reason.
        required: [en]
        additionalProperties: 
          type: string
    required: [id, name]
    example:
      id: '123' # Note the quotes to force the value as a string
      name: 
        en: English text
        de: Deutscher Text

Il n'y a pas non plus d'indice en ce que le résultat aura un code de langue en tant que clé et le texte en tant que valeur de la carte de hachage.

Des choses comme celle-là peuvent être documentées verbalement dans la description.

l'exemple ne semble pas non plus fonctionner comme prévu. Il génère un $ plié vide: dans l'interface utilisateur.

Vous ne savez pas quel était le problème avec votre spécification d'origine, mais la spécification ci-dessus est valide et semble bien dans Swagger Editor .

Model schema in Swagger Editor

12
Helen

Si vous êtes toujours en phase de conception, au lieu d'utiliser des clés dynamiques, vous pouvez utiliser toutes les autres références de langage dans un tableau avec une structure telle que:

{
"launguage":"en"
"text":"Hello World"
}

Cela simplifierait beaucoup les choses, et puisque vous ne vous fiez pas à additionalProperties, vos bibliothèques clientes générées le trouveront plus facilement.

0
Sanket Berde