Utiliser des valeurs d'exemple différentes pour les paramètres dans Swagger 2?

Question

J'ai une API qui utilise la même définition dans plus d'une place, mais je veux inclure des exemples différents pour les différents endroits.

Pour donner un peu de contexte, je:

parameters: 
- in: body 
    description: The user object for the new user 
    name: body 
    schema: 
    "$ref": "#/definitions/User" 

qui utilise l'objet utilisateur. L'objet Utilisateur est également renvoyé lorsqu'un utilisateur se connecte et contient plus d'informations que ce qui est utilisé pour créer l'utilisateur, par exemple, l'ID utilisateur.

J'ai un exemple sur la définition, mais existe-t-il un moyen pour que je puisse avoir un exemple séparé pour le paramètre de corps de point de terminaison POST/user?

Answer 1

Je suggère d'avoir deux objets différents pour l'utilisateur: UserCreate qui est pour créer (et peut-être mettre à jour) et UserDetail qui est retourné par post/put/get avec tous les détails. Cela permet différents exemples comme vous pouvez le voir ci-dessous.

Vous pouvez avoir UserDetail hériter toutes les propriétés de UserCreate en utilisant la construction allOf. Dans cet exemple, ils partagent le nom et l'adresse e-mail et UserDetail possède un ID et une propriété href supplémentaires:

paths: 
    /users: 
    post: 
     parameters: 
     - in: body 
     name: body 
     schema: 
      $ref: '#/definitions/UserCreate'  
     responses: 
     201: 
      description: The created user 
      schema: 
      $ref: '#/definitions/UserDetail' 
    /users/{id}: 
    get: 
     parameters: 
     - in: path 
     name: id 
     type: string 
     required: true 
     responses: 
     200: 
      description: The user 
      schema: 
      $ref: '#/definitions/UserDetail' 

definitions: 
    UserCreate: 
    properties: 
     name: 
     type: string 
     email: 
     type: string 
    example: 
    - name: Bob 
     email: bob@somewhere.com 
    UserDetail: 
    allOf: 
    - $ref: '#/definitions/UserCreate' 
    - properties: 
     id: 
      type: string 
     href: 
      type: string 
     example: 
     - id: 123 
     href: /users/123 
     name: Bob 
     email: bob@somewhere.com