wake-up-neo.com

Swagger 2.0 - wie man "den einen oder anderen" Parameter benötigt?

Ich habe eine Swagger 2.0-Ressource, die unten definiert ist. Wie kann ich "param1 oder param2" erforderlich machen? Der Aufrufer muss entweder param1 oder param2 übergeben.

/some/res:
put:
  summary: some resource
  responses:
    200:
      description: Successful response
      schema:
        $ref: '#/definitions/SomeResponse'
  parameters:
    - name: param1
      type: string
      description: param1
      in: formData
      required: false
    - name: param2
      type: string
      description: param2
      in: formData
      required: false
44
Vineet Bhatia

Die OpenAPI-Spezifikation (fka Swagger) unterstützt keine bedingten oder sich gegenseitig ausschließenden Parameter (jeglichen Typs).

Es gibt eine offene Feature-Anfrage:
nterstützt Abhängigkeiten zwischen Abfrageparametern

42
Ron

Im Abschnitt Parameterabhängigkeiten der Parameter beschreiben Swagger-Dokumentation:

Swagger unterstützt keine Parameterabhängigkeiten und sich gegenseitig ausschließende Parameter. Es gibt eine offene Feature-Anfrage unter https://github.com/OAI/OpenAPI-Specification/issues/256 .

Ab Juni 2017 hatte diese Ausgabe 21 positive Bewertungen, was sie zur dritthöchsten bewerteten Ausgabe im Projekt macht.

5
Trenton

Die Swagger-Spezifikation unterstützt keine bedingten Anforderungen oder das Einschließen/Ausschließen von Parametern.

Ich würde vorschlagen, in der Beschreibung deutlich Ihre Regeln für das Einschließen/Ausschließen von Abfrageparametern anzugeben. Überprüfen Sie anschließend die Parameter anhand eines Validierungsframeworks, das von Ihrer Sprache abhängt (z. B. javax.validation für Java, erneutes Validieren für erneutes Validieren usw.).

3
Gene Ames

Das spezielle Szenario in dieser Frage - eine POST/PUT/PATCH-Anforderung mit einem Formulardatentext, der entweder param1 oder param2 - kann mit OpenAPI 3.0 und oneOf definiert werden:

openapi: 3.0.0
...

paths:
  /some/res:
    put:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  properties:
                    param1:
                      type: string
                  required:
                    - param1
                  additionalProperties: false
                - type: object
                  properties:
                    param2:
                      type: string
                  required:
                    - param2
                  additionalProperties: false

Hinweis für Benutzer der Swagger-Benutzeroberfläche: Formulardaten-Benutzeroberfläche und Beispiel-Rendering für oneOf Schemata sind noch nicht verfügbar für OpenAPI 3.0-Definitionen.

3
Helen