Comment documenter plusieurs types de contenu en réponse réussie GET dans fanfaronnades

Question

Disons que nous avons un spec exemple JSON Swagger:

{ 
"swagger": "2.0", 
"info": { 
    "version": "1.0.0", 
    "title": "Some API" 
}, 
"basePath": "/api/v1", 
"consumes": [ 
    "application/json" 
], 
"produces": [ 
    "application/json", 
    "text/csv" 
], 
"paths": { 
    "/some/endpoint": { 
     "get": { 
      "parameters": [ 
       { 
        "in": "body", 
        "name": "body", 
        "required": false, 
        "schema": { 
         "$ref": "#/definitions/BodyParamsDefinition" 
        } 
       } 
      ], 
      "responses": { 
       "200": { ?? } ... 

Il existe deux types de contenus qui peuvent être produits:

demande
• /JSON
• text/csv

réponse par défaut pour GET /some/endpoint est un fichier csv, mais si le paramètre de requête format est utilisé comme ceci /some/endpoint?format=json, la réponse serait au format json.

J'ai de la difficulté à trouver comment terminer mes spécifications avec des réponses appropriées. Lorsque j'utilise cette approche: https://swagger.io/docs/specification/describing-responses/ i obtenir une erreur de validation: ...get.responses['200'] should NOT have additional properties

Answer 1

Vous êtes presque là, il vous suffit de définir un schema pour la réponse. Ce schema définit la structure de réponse pour tous les types de contenu associés à ce code d'état.

Par exemple, si l'opération retourne cette JSON:

[ 
    { 
    "petType": "dog", 
    "name": "Fluffy" 
    }, 
    { 
    "petType": "cat", 
    "name": "Crookshanks" 
    } 
] 

et ce CSV:

petType,name 
dog,Fluffy 
cat,Crookshanks 

que vous utilisez:

# YAML 
responses: 
    200: 
    description: OK 
    schema: 
     type: array 
     items: 
     type: object 
     properties: 
      petType: 
      type: string 
      name: 
      type: string 

Plus d'info: Describing Responses

Dans OpenAPI 3.0, les définitions de type de contenu ont été améliorés et les schémas peuvent varier selon le type de contenu:

openapi: 3.0.0 
... 

paths: 
    /some/endpoint: 
    get: 
     responses: 
     '200': 
      description: OK 
      content: 
      # JSON data is an object 
      application/json: 
       schema: 
       type: object 
       properties: 
        message: 
        type: string 
      # CSV data is a string of text 
      text/csv: 
       schema: 
       type: string 

Default response for GET /some/endpoint is a csv file, but if the format query param is used like this /some/endpoint?format=json , the response would be in json format.

Il y a actuellement aucun moyen de cartographier des réponses spécifiques aux paramètres de fonctionnement spécifiques, mais sont plusieurs propositions connexes dans le référentiel de spécification OpenAPI:

• Accommodate legacy APIs by allowing query parameters in the path
• Querystring in Path Specification
• Support an operation to have multiple specifications per path
• Overloading