OpenAPI - bagaimana menjelaskan parameter kueri?

Question

Saya mencoba mencari cara untuk mendokumentasikan dua parameter kueri saya di OpenAPI.

Penyaringan

Pemfilteran saya mengikuti rekomendasi JSON: API , yang berupa, misalnya:

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

The filterkunci adalah array asosiatif yang dapat berisi daftar set nama sumber daya dalam API saya. Nilai yang ditetapkan ke setiap kunci filter bisa berupa satu id atau daftar id yang dipisahkan koma.

Penyortiran

Untuk pengurutan, ikuti juga JSON: rekomendasi API , jadi seperti ini:

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

The sortparameter permintaan ditugaskan nilai lapangan atau sejenisnya daftar dipisahkan koma bidang semacam. Perhatikan bahwa tanda minus yang mengawali heightbidang menunjukkan urutan menurun.

Pertanyaan

Bagaimana cara merepresentasikan pemfilteran dan pengurutan saya di OpenAPI ?

Misalnya, saya tidak yakin mungkin bagi saya untuk menentukan bahwa kunci filter adalah array asosiatif, atau yang menerima daftar id yang dipisahkan koma. Masalah yang hampir sama untuk sort: bagaimana cara merepresentasikan daftar kolom sortir yang dipisahkan koma?

Answer 1

Pendekatan di bawah ini akan membantu

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

Sebagian mirip dengan pertanyaan yang dibagikan @Helen. Ini akan memungkinkan Anda untuk menggunakannya seperti pada gambar di bawah ini

Dan perintah cURL masing-masing

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

Anda juga dapat menentukan filterparameter dengan cara di bawah ini

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

Ini akan menghasilkan UI yang lebih komprehensif seperti di bawah ini

Kemudian permintaan cURL terlihat seperti di bawah ini

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

Dan Anda mungkin tidak perlu anyOfkarena ini terkait dengan pewarisan untuk situasi ketika metode dapat mengembalikan objek dari kelas dasar atau sub-kelasnya.

Lihat oneof-anyof-allof-not - Spesifikasi OpenAPI untuk info lebih lanjut tentangnya.