OpenAPI - wie werden Abfrageparameter beschrieben?

Question

Ich versuche herauszufinden, wie ich zwei meiner Abfrageparameter in OpenAPI dokumentieren kann.

Filtern

Meine Filterung folgt den Empfehlungen von JSON: API , die beispielsweise folgende Form haben:

• ?filter[post]=1,2,3
• ?filter[post]=1,2,3&filter[author]=5

Der filterSchlüssel ist ein assoziatives Array, das eine festgelegte Liste von Ressourcennamen in meiner API enthalten kann. Der jedem Filterschlüssel zugewiesene Wert ist entweder eine einzelne ID oder eine Liste von durch Kommas getrennten IDs.

Sortierung

Zum Sortieren folgt auch die JSON: API-Empfehlung , also so etwas wie diese:

• ?sort=age
• ?sort=age,-height

Dem sortAbfrageparameter wird der Wert eines Sortierfelds oder einer Liste von durch Kommas getrennten Sortierfeldern zugewiesen. Beachten Sie, dass das Minuszeichen vor dem heightFeld eine absteigende Sortierung anzeigt.

Frage

Wie stelle ich meine Filterung und Sortierung in OpenAPI dar ?

Ich bin mir beispielsweise nicht sicher, ob ich angeben kann, dass der Filterschlüssel ein assoziatives Array ist oder eine durch Kommas getrennte Liste von IDs akzeptiert. Fast das gleiche Problem beim Sortieren: Wie wird eine durch Kommas getrennte Liste von Sortierfeldern dargestellt?

Answer 1

Der folgende Ansatz sollte helfen

parameters:
  - in: query
    name: fields
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: string
        author:
          type: string
  - in: query
    name: sort
    schema:
      type: array
      items:
        type: string
        enum:
          - age
          - height

Ein Teil davon ähnelt der Frage, die @Helen geteilt hat. Damit können Sie es wie im folgenden Bild verwenden

Und der jeweilige cURL-Befehl

curl -X GET "https://editor.swagger.io/user?filter[post]=1,2&filter[author]=3,4&sort=age&sort=height" -H  "accept: */*"

Sie können den filterParameter auch wie folgt definieren

parameters:
  - in: query
    name: filter
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: array
          items:
            type: string
        author:
          type: array
          items:
            type: string

Dies führt dazu, dass die Benutzeroberfläche wie unten beschrieben umfassender ist

Dann sieht die cURL-Anfrage wie folgt aus

curl -X GET "https://editor.swagger.io/user?filter[post]=1&filter[post]=2&filter[author]=3&filter[author]=4&sort=age&sort=height" -H  "accept: */*"

Und Sie sollten dies wahrscheinlich nicht benötigen, anyOfda es sich um eine Vererbung handelt, wenn eine Methode möglicherweise ein Objekt der Basisklasse oder einer ihrer Unterklassen zurückgibt.

Weitere Informationen hierzu finden Sie in einer OpenAPI-Spezifikation .