web-dev-qa-db-fra.com

Swagger; spécifier deux réponses avec le même code en fonction d'un paramètre facultatif

Cette question n'est pas un doublon de ( Swagger - Spécifiez une propriété d'objet facultatif ou des réponses multiples ) car cet OP essayait de renvoyer un 200 ou un 400. 

J'ai une GET avec un paramètre optionnel; Par exemple, GET /endpoint?selector=foo. 

Je veux renvoyer un 200 dont le schéma est différent selon que le paramètre a été passé, par exemple:

GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah  -> {200, schema_2}

Dans le YAML, j'ai essayé d'avoir deux codes 200, mais le spectateur les écrase comme si je n'en avais spécifié qu'un. 

Y a-t-il un moyen de faire cela?

Edit: ce qui suit semble lié: https://github.com/OAI/OpenAPI-Specification/issues/270

swaggerswagger-2.0
20
Tommy

OpenAPI 3.0 vous permet d'utiliser oneOf pour définir plusieurs corps de requête ou de réponse possibles pour la même opération:

openapi: 3.0.0
...
paths:
  /path:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'

Cependant, il n'est pas possible de mapper des réponses spécifiques à des valeurs de paramètres spécifiques. Vous devrez documenter ces détails verbalement dans la variable description.


Note pour les utilisateurs de l'interface utilisateur Swagger: Au moment de l'écriture de cet article (décembre 2018), l'interface utilisateur Swagger ne génère pas automatiquement d'exemples pour les schémas oneOf et anyOf. Vous pouvez suivre ce problème pour les mises à jour.

Pour résoudre ce problème, vous pouvez spécifier une réponse example manuellement. Utilisez une seule example et non plusieurs examples (la prise en charge de plusieurs exemples est également pas encore disponible dans l'interface utilisateur Swagger).

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'
              example:   # <--------
                foo: bar
9
Helen

Je voulais la même chose et j'ai trouvé une solution de contournement qui semble fonctionner:

Je viens de définir deux chemins différents:

/path:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseOne'
(...)

/path?parameter=value:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseTwo'
(...)

Les chemins fonctionnent sur l’éditeur swagger. Je peux même documenter chaque option différemment et mettre des paramètres optionnels qui ne peuvent figurer que sur le second cas, ce qui rend la documentation API beaucoup plus propre. En utilisant operationId, vous pouvez générer des noms de nettoyeur pour les méthodes API générées.

J'ai posté la même solution ici ( https://github.com/OAI/OpenAPI-Specification/issues/270 ) pour vérifier si quelque chose me manque. 

Je comprends que ce n’est pas explicitement autorisé/encouragé à le faire (ni que j’ai trouvé un endroit le refusant explicitement). Mais comme solution de contournement, et étant le seul moyen de documenter une API avec ce comportement dans la spécification en cours, ressemble à une option.

J'ai rencontré deux problèmes: 

  • Le code Java de l'URL générique échappe au signe "=", il ne fonctionnera donc que sivous corrigez cela dans le code généré. Cela se produit probablement dans d'autres générateurs de code
  • Si vous avez plus de paramètres de requête, un "?" Supplémentaire sera ajouté. et échouer;

Si ce ne sont pas des bloqueurs, cela vous permettra au moins de documenter correctement de tels cas et de tester avec l'éditeur swagger. 

2
CristianTM