web-dev-qa-db-fra.com

Types de données génériques OpenAPI 3.0

Comment puis-je décrire au mieux un type de réponse générique qui inclut le type de données réel dans OpenAPI 3.

Exemple simplifié:

ApiResponse:
  data: object
  error: string

Mais le point de terminaison/users devrait donner:

ApiResponse<List<User>>

Voilà donc essentiellement:

ApiResponse:
  data: List<User>
  error: string

Il semble que ce ne soit pas possible pour le moment, mais je veux juste m'en assurer. Je suppose que la meilleure façon de le faire maintenant est de faire des réponses nommées pour chaque appel et d'utiliser allOf pour faire référence à ApiResponse et aux données implémentées: valeur spécifique.

swaggeropenapi
12
Jørgen

Je recherche des types génériques beaucoup de temps, mais il n'y a aucun moyen de définir un type générique dans OpenAPI3. La manière la plus simple consiste à utiliser allOf et $ ref en même temps. Supposons qu'il existe un schéma de liste comme suit:

List:
   type: object
   properties:
       page_number:
          type: integer
       page_count:
          type: integer

Et le schéma du livre est

Book:
   type: object
   properties:
       title:
          type: string
       summary:
          type: string

Pour renvoyer une liste, le chemin est:

  /api/v1/books:
      get:
        responses:
          default:  
            description: description text
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/List'
                    - type: object
                      properties:
                        items: 
                          type: array
                          items: 
                            $ref: '#/components/schemas/Book'

Ce résultat est

   {
        "page_number": 1,
        "page_count": 10,
        "items": [{
            "title": "title",
            "description": ""
        },
        ... ]
    }

En fait, c'est une liste de livres. Comme vous pouvez le voir, vous ajoutez en même temps les principaux attributs de la liste au résultat et au type d'élément de liste. Vous pouvez également répéter ce modèle pour les autres:

  /api/v1/authors:
      get:
        responses:
          default:  
            description: description text
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/List'
                    - type: object
                      properties:
                        items: 
                          type: array
                          items: 
                            $ref: '#/components/schemas/Author'
1
مصطفی

Eh bien, vous pouvez utiliser le type object avec additionalProperties avec la valeur vraie pour obtenir des objets de forme libre.

0
Pablo Santa Cruz