Swagger - Formdata avec un article de forme-urlEncoded

Question

J'essaye de créer un document de fanfare pour mon api et je suis un peu coincé avec quelque chose que j'imagine est assez facile à réaliser une fois que vous savez comment.

J'ai un point de terminaison qui accepte un poste en tant que multipart/form-data (Comme il nécessite un téléchargement de fichier), cependant un de ces éléments (prétendre qu'il s'appelle "carParts" pour cet exemple), est un contenu FormURLEncoded type qui est une liste de paires clé/valeur.

Ainsi la structure est quelque chose comme:

RARnom: Ford
Carage: 20
Carparts: roues = 4 & corne = true & pare-brise = cassé

Mon problème est que je Je ne sais pas comment l'exprimer ("carParts") dans le document swagger. La seule façon que je peux voir pour le faire est de mettre l'élément "carParts" à un type de chaîne, mais ensuite je perds le point de swagger, en ce sens que je veux "roues", "klaxon" et "pare-brise" être des champs explicites, pas seulement une seule chaîne form-urlEncoded.

Est-il possible de faire cela avec swagger? Si non, je suppose que la seule autre option est de changer mon API pour avoir les éléments "carParts" comme une liste plate plutôt que comme une structure (ie perdre le niveau parent "carParts" et avoir les éléments juste autres éléments de données de niveau supérieur). Cela semble être le moyen le plus direct, mais il est dommage que je doive modifier l'API pour y parvenir (pas un problème majeur, je ne me sens pas bien).

Answer 1

Ceci est possible dans OpenAPI 3.0, mais pas dans OpenAPI/Swagger 2.0.

Dans OpenAPI/Swagger 2.0, les champs de formulaire ne peuvent pas être des objets, vous devrez donc définir carParts comme une chaîne ou comme un tableau de primitives.

Dans OpenAPI 3.0, vous pouvez avoir des objets dans des champs de formulaire, et vous pouvez spécifier comment ces objets sont sérialisés. Il n'y a pas beaucoup d'exemples actuellement, mais je pense que votre cas peut être décrit comme suit:

paths: 
    /something: 
    post: 
     requestBody: 
     required: true 
     content: 

      multipart/form-data: 
      # Form fields (carName, etc.) are defined as object properties 
      schema: 
       type: object 
       properties: 
       carName: 
        type: string 
       carAge: 
        type: string 
       carParts: 
        type: object 
        properties: 
        wheels: 
         type: integer 
        horn: 
         type: boolean 
        windscreen: 
         type: string 
      # By default, the "carParts" object will be serialized as application/json, 
      # but we can override the serialization method to be form-urlencoded 
      encoding: 
       carParts: 
       contentType: application/x-www-form-urlencoded 

partie pertinente de la spécification: Special Considerations for multipart Content.