Objek OpenAPI JSON sebagai Parameter Pertanyaan

1. Gambaran keseluruhan

Dalam tutorial ini, kita akan belajar bagaimana bekerja dengan objek JSON sebagai parameter pertanyaan menggunakan OpenAPI .

2. Parameter Pertanyaan dalam OpenAPI 2

OpenAPI 2 tidak menyokong objek sebagai parameter pertanyaan ; hanya nilai primitif dan susunan primitif yang disokong.

Oleh kerana itu, kami ingin menentukan parameter JSON kami sebagai rentetan.

Untuk melihatnya dalam tindakan, mari kita tentukan parameter yang disebut param sebagai rentetan , walaupun kita akan menguraikannya sebagai JSON di backend kita:

swagger: "2.0" ... paths: /tickets: get: tags: - "tickets" summary: "Send an JSON Object as a query param" parameters: - name: "params" in: "path" description: "{\"type\":\"foo\",\"color\":\"green\"}" required: true type: "string" 

Oleh itu, bukannya:

GET //localhost:8080/api/tickets?type=foo&color=green

kami akan melakukan:

GET //localhost:8080/api/tickets?params={"type":"foo","color":"green"}

3. Pertanyaan Param di OpenAPI 3

OpenAPI 3 memperkenalkan sokongan untuk objek sebagai parameter pertanyaan.

Untuk menentukan parameter JSON, kita perlu menambahkan bahagian kandungan pada definisi kita yang merangkumi jenis dan skema MIME:

openapi: 3.0.1 ... paths: /tickets: get: tags: - tickets summary: Send an JSON Object as a query param parameters: - name: params in: query description: '{"type":"foo","color":"green"}' required: true schema: type: object properties: type: type: "string" color: type: "string" 

Permintaan kami kini dapat dilihat seperti:

GET //localhost:8080/api/tickets?params[type]=foo┬Âms[color]=green

Sebenarnya, ia masih boleh kelihatan seperti:

GET //localhost:8080/api/tickets?params={"type":"foo","color":"green"}

Pilihan pertama membolehkan kami menggunakan pengesahan parameter, yang akan memberi tahu kami jika ada sesuatu yang salah sebelum permintaan dibuat.

Dengan pilihan kedua, kami memperdagangkannya untuk kawalan yang lebih besar pada backend serta keserasian OpenAPI 2.

4. Pengekodan URL

Penting untuk diperhatikan bahawa, dalam membuat keputusan ini untuk memindahkan parameter permintaan sebagai objek JSON, kami ingin memasukkan URL parameter tersebut untuk memastikan pengangkutan yang selamat.

Oleh itu, untuk menghantar URL berikut:

GET /tickets?params={"type":"foo","color":"green"}

Kami sebenarnya akan melakukan:

GET /tickets?params=%7B%22type%22%3A%22foo%22%2C%22color%22%3A%22green%22%7D

5. Batasan

Juga, ingatlah batasan melewati objek JSON sebagai sekumpulan parameter pertanyaan:

  • pengurangan keselamatan
  • panjang parameter yang terhad

Sebagai contoh, semakin banyak data yang kita masukkan dalam parameter pertanyaan , semakin banyak yang muncul dalam log pelayan dan semakin tinggi potensi pendedahan data sensitif.

Juga, satu parameter pertanyaan tidak boleh melebihi 2048 aksara. Sudah tentu, kita semua dapat membayangkan senario di mana objek JSON kita lebih besar daripada itu. Secara praktikal, pengekodan URL rentetan JSON kami sebenarnya akan mengehadkan kami kepada kira-kira 1000 aksara untuk muatan kami.

Satu penyelesaian adalah dengan menghantar Objek JSON yang lebih besar di dalam badan. Dengan cara ini, kami menyelesaikan masalah keselamatan dan had panjang JSON.

Sebenarnya, GET atau POST kedua-duanya menyokong ini. Salah satu sebab untuk menghantar lebih banyak GET adalah mengekalkan semantik RESTful API kami.

Sudah tentu, ia agak tidak biasa dan tidak disokong secara universal. Sebagai contoh, beberapa perpustakaan HTTP JavaScript tidak membenarkan permintaan GET untuk memiliki badan permintaan.

Ringkasnya, pilihan ini adalah pertukaran antara semantik dan keserasian sejagat.

6. Kesimpulannya

Kesimpulannya, dalam artikel ini kita belajar bagaimana menentukan objek JSON sebagai parameter pertanyaan menggunakan OpenAPI. Kemudian, kami melihat beberapa implikasi pada bahagian belakang.

Definisi OpenAPI yang lengkap untuk contoh ini boleh didapati di GitHub.