OpenAPI - jak opisać parametry zapytania?

Question

Próbuję dowiedzieć się, jak udokumentować dwa z moich parametrów zapytania w OpenAPI.

Filtracja

Moje filtrowanie jest zgodne z zaleceniami JSON: API , które przybiera postać np .:

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

filterKluczem jest tablica asocjacyjna, która może zawierać listę zestawu nazw zasobów w moim API. Wartość przypisana do każdego klucza filtru to pojedynczy identyfikator lub lista identyfikatorów oddzielonych przecinkami.

Sortowanie

W przypadku sortowania również postępuje zgodnie z zaleceniem JSON: API , więc coś takiego:

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

sortParametr zapytania jest przypisana wartość polu jeden rodzaj lub listy rozdzielonych przecinkami pola sortowania. Zwróć uwagę, że znak minus poprzedzający heightpole wskazuje na sortowanie malejące.

Pytanie

Jak mogę przedstawić moje filtrowanie i sortowanie w OpenAPI ?

Na przykład nie jestem pewien, czy mogę określić, czy klucz filtru jest tablicą asocjacyjną lub czy akceptuje listę identyfikatorów oddzielonych przecinkami. Prawie ten sam problem dla sortowania: jak przedstawić listę pól sortowania oddzielonych przecinkami?

Answer 1

Poniższe podejście powinno pomóc

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

Część tego jest podobna do pytania, które podzieliła się @Helen. Umożliwi ci to użycie go jak na poniższym obrazku

I odpowiednie polecenie cURL

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

Możesz również zdefiniować filterparametr w poniższy sposób

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

Spowoduje to, że interfejs użytkownika będzie bardziej wszechstronny, jak poniżej

Wtedy żądanie cURL wygląda jak poniżej

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: */*"

I prawdopodobnie nie powinieneś tego potrzebować, anyOfponieważ jest to związane z dziedziczeniem w sytuacjach, gdy metoda może zwrócić obiekt klasy bazowej lub dowolnej jej podklasy.

Aby uzyskać więcej informacji, zapoznaj się ze specyfikacją Oneof-anyof-allof-not - OpenAPI .