web-dev-qa-db-de.com

Stolzieren; Geben Sie zwei Antworten mit demselben Code basierend auf optionalen Parametern an

Diese Frage ist kein Duplikat von ( Swagger - Angabe optionaler Objekteigenschaften oder mehrerer Antworten ), da das OP versucht hat, eine 200 oder eine 400 zurückzugeben. 

Ich habe eine GET mit einem optionalen Parameter; z.B. GET /endpoint?selector=foo

Ich möchte eine 200 zurückgeben, deren Schema davon abhängt, ob der Parameter übergeben wurde, z.

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

Im Yaml habe ich versucht, zwei 200 Codes zu haben, aber der Zuschauer drückt sie nieder, als würde ich nur einen Code angeben. 

Gibt es eine Möglichkeit, dies zu tun?

Edit: Folgendes scheint verwandt zu sein: https://github.com/OAI/OpenAPI-Specification/issues/270

20
Tommy

In OpenAPI 3.0 können Sie mit oneOf mehrere mögliche Anforderungstextkörper oder Antworttextkörper für dieselbe Operation definieren:

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

Es ist jedoch nicht möglich, bestimmten Antworten bestimmte Parameterwerte zuzuordnen. Sie müssen diese Besonderheiten in der description verbal dokumentieren.


Hinweis für Benutzer der Swagger-Benutzeroberfläche: Zum Zeitpunkt des Schreibens (Dezember 2018) generiert die Swagger-Benutzeroberfläche nicht automatisch Beispiele für oneOf- und anyOf-Schemas. Sie können diesem Problem für Updates folgen.

Als Problemumgehung können Sie manuell eine Antwort example angeben. Verwenden Sie eine einzelne example, nicht mehrere examples (Unterstützung für mehrere Beispiele ist auch noch nicht verfügbar in der Swagger-Benutzeroberfläche).

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

Ich wollte das Gleiche und kam zu einer Problemumgehung, die scheinbar funktioniert:

Ich habe gerade zwei verschiedene Pfade definiert:

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

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

Pfade funktionieren im Swagger-Editor. Ich kann sogar jede Option anders dokumentieren und optionale Parameter angeben, die möglicherweise nur im zweiten Fall enthalten sind, wodurch das API-Dokument viel sauberer wird. Mit operationId können Sie sauberere Namen für die generierten API-Methoden generieren.

Ich habe hier die gleiche Lösung ( https://github.com/OAI/OpenAPI-Specification/issues/270 ) veröffentlicht, um zu überprüfen, ob etwas mehr fehlt. 

Ich verstehe, dass es nicht ausdrücklich erlaubt/ermutigt wird, dies zu tun (ich habe auch nicht herausgefunden, dass irgendwo dies ausdrücklich verboten ist). Aber als Workaround und als einzige Möglichkeit, eine API mit diesem Verhalten in der aktuellen Spezifikation zu dokumentieren, sieht es aus wie eine Option.

Zwei Probleme habe ich damit herausgefunden: 

  • Die Java-Code-Gen-URL wird dem "=" - Zeichen entzogen, daher funktioniert sie nicht, es sei denn, Sie müssen dies im generierten Code beheben. Wahrscheinlich geschieht dies in anderen Code-Generatoren.
  • Wenn Sie mehr Abfrageparameter haben, wird ein zusätzliches "?" und scheitern;

Wenn dies keine Blocker sind, können Sie zumindest solche Fälle ordnungsgemäß dokumentieren und mit dem Swagger-Editor testen. 

2
CristianTM