OpenAPI - sorgu parametreleri nasıl tanımlanır?

Question

Sorgu parametrelerimden ikisini OpenAPI'de nasıl belgelendireceğimi anlamaya çalışıyorum.

Filtreleme

Filtrelemem , örneğin şu biçimdeki JSON: API önerilerini takip eder :

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

filterAnahtar benim API kaynak adlarının bir dizi listesi içerebilir birleşmeli dizisidir. Her filtre anahtarına atanan değer, tek bir kimlik veya virgülle ayrılmış kimlikler listesidir.

Sıralama

Sıralama için JSON: API önerisini de takip eder , bu nedenle aşağıdakiler gibi bir şey:

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

sortSorgu parametre, bir sıralama alanı veya virgülle ayrılmış sıralama alanları listesinin değer atanır. heightAlanın önekini oluşturan eksi işaretinin azalan sıralamayı gösterdiğine dikkat edin.

Soru

OpenAPI'de filtrelememi ve sıralamamı nasıl temsil ederim ?

Örneğin, filtre anahtarının ilişkilendirilebilir bir dizi olduğunu veya virgülle ayrılmış bir kimlik listesini kabul ettiğini belirtmemin mümkün olduğundan emin değilim. Sıralama için neredeyse aynı sorun: sıralama alanlarının virgülle ayrılmış bir listesi nasıl temsil edilir?

Answer 1

Aşağıdaki yaklaşım yardımcı olmalı

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

Bir kısmı @Helen'in paylaştığı soruya benziyor. Aşağıdaki görüntüdeki gibi kullanmanızı sağlayacaktır

Ve ilgili cURL komutu

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

filterParametreyi aşağıdaki şekilde de tanımlayabilirsiniz.

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

Bu, kullanıcı arayüzünün aşağıdaki gibi daha kapsamlı olmasına neden olacaktır.

Daha sonra cURL isteği aşağıdaki gibi görünür

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

Ve anyOfbir yöntemin temel sınıftan bir nesneyi veya onun alt sınıflarından herhangi birini döndürebileceği durumlar için kalıtımla ilgili olduğundan muhtemelen ihtiyacınız olmayacaktır .

Daha fazla bilgi için oneof-anyof-allof-not - OpenAPI Spesifikasyonuna bakın.