Swagger; geben Sie zwei Antworten mit dem gleichen code basiert auf optionale parameter

Diese Frage ist nicht duplizieren ( Swagger - Geben Sie Optional Objekt-Eigenschaft oder Mehrere Antworten ), weil, die OP wurde versucht, wieder ein 200 oder 400.

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

Möchte ich wieder ein 200, deren schema ist unterschiedlich, abhängig davon, ob der parameter übergeben wurde, z.B.:

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

In der yaml, habe ich versucht, mit zwei 200-codes, sondern der Zuschauer drückt Sie nieder, wie wenn ich nur eines angegeben.

Gibt es eine Möglichkeit, dies zu tun?

Edit: der folgende Zusammenhang: https://github.com/OAI/OpenAPI-Specification/issues/270

InformationsquelleAutor Tommy | 2016-04-12
  1. 13

    Open API 3.0 können Sie oneOf zu definieren, die mehrere mögliche Anfrage stellen oder Resonanz-Körper für die gleiche operation:

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

    Jedoch es nicht möglich, die map-spezifische response-schemas spezifische parameter-Werte. Sie müssen dokumentieren diese Besonderheiten mündlich in der description von der response, operation und/oder parameter.

    Hier ist eine, die möglicherweise mit Erweiterung Anfrage:

    Erlauben operationObject überlastung mit get-^ nach-^ etc


    Hinweis für Swagger-UI-Nutzer: Als des Schreibens dieses Artikels (Dezember 2018) Swagger-UI nicht automatisch generieren Beispiele für oneOf und anyOf schemas. Sie können Folgen Sie dieses Problem für updates.

    Als Problemumgehung können Sie eine Antwort example oder examples manuell. Beachten Sie, dass die Verwendung mehrerer examples erfordern Swagger UI 3.23.0+ oder-Stolzieren-Editor 3.6.31+.

          responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'
              example:   # <--------
                foo: bar
    • Ist Swagger auf Open API 3?
    • ist ein Sammelbegriff für viele Projekte - Swagger-Editor, Swagger-UI, etc. Welches Projekt meinst du?
    • es erscheint "swagger-Spezifikation" wurde umbenannt in "open-api-Spezifikation" nach diesem, ich wusste das nicht, vielen Dank: stolzieren.io/Spezifikation
    • Ich habe implementiert die oben in Fors, aber ich bin nicht zu sehen, jede Antwort in der Dokumentation. Sicherlich, wenn Sie geben zwei mögliche Antworten, es zeigt Sie beide in den docs? Ansonsten, was ist der Punkt in der feature oder bin ich etwas fehlt?
    • Es ist ein bekanntes Problem (oder eher nicht-implementierte feature) in Swagger-UI. Ich aktualisierte die Antwort und fügte einen workaround.
    • vielen Dank für Ihre prompte Antwort. Bin ich Recht in der Annahme, dass es auch ein Problem mit der Angabe "Mehrere Beispiele'? Kurzum, ich bin auf der Suche zum Dokument mehrere Beispiel-Antworten für die gleichen HTTP-code auf eine Anfrage. Ich habe meine Forschung getan, und es scheint, dass dies möglich sein kann, aber es ist noch nicht in der Benutzeroberfläche übernommen...
    • Wenn du meinst examples (plural) - Sie sind auch noch nicht implementiert. Unterstützung für examples ist verfolgte hier.
    • Perfekt, danke sehr 🙂

    InformationsquelleAutor Helen
  2. 2

    Wollte ich die gleiche Sache, und ich kam mit einem workaround zu funktionieren scheint:

    Ich habe gerade definiert zwei unterschiedliche Wege:

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

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

    Pfade arbeiten, die auf swagger-editor. Ich kann sogar Dokument jede option unterschiedlich und stellen optionale Parameter, die nur auf den zweiten Fall toguether, die den API-doc viel sauberer. Mit operationId Sie können zu generieren, Reiniger Namen für die generierte API-Methoden.

    Ive posted die gleiche Lösung hier ( https://github.com/OAI/OpenAPI-Specification/issues/270 ), um zu überprüfen, wenn ich bin fehlt etwas mehr.

    Ich verstehe es nicht explizit erlaubt/aufgefordert, es zu tun (weder fand ich einen Ort explizit verbieten es). Aber als workaround, und der einzige Weg, um Dokument eine API mit diesem Verhalten in der aktuellen Spezifikation, sieht aus wie eine option.

    Zwei Probleme, die Ich habe herausgefunden mit:

    • Java-code-gen-URL entgeht dem " = " - Zeichen, also es wird nicht funktionieren, es sei denn,
      fixieren Sie diese in den generierten code. Wahrscheinlich passiert es in anderen code
      - Generatoren.
    • Wenn Sie mehrere query-Parameter es wird das hinzufügen eines zusätzlichen "?" und scheitern;

    Wenn es diese nicht Blocker, die es zumindest ermöglichen, Sie zu dokumentieren ordnungsgemäß solchen Fällen und damit die Untersuchung mit swagger-editor.

    InformationsquelleAutor CristianTM
Schreibe einen Kommentar