Cara Menggunakan Diskriminator untuk Mencocokkan Struktur Parameter API Berbeda di Apidog

Dalam artikel kami sebelumnya "Apa yang Harus Dilakukan Ketika API Memiliki Beberapa Struktur Parameter", kami membahas bahwa ketika sebuah API memerlukan struktur parameter yang berbeda, Anda dapat menggunakan oneOf, anyOf, atau allOf di Apidog untuk mendefinisikannya.

Setelah Anda mengatur struktur parameter menggunakan komposisi skema ini, dan parameter Anda menyertakan bidang yang mengidentifikasi tipe data, Anda dapat membuat dokumentasi menjadi lebih jelas dengan menggunakan fitur discriminator dari spesifikasi OpenAPI untuk membedakan antara skema secara lebih intuitif.

Apa itu Discriminator?

Dalam OpenAPI, peran discriminator adalah untuk mengimplementasikan "polimorfisme" dari pemrograman berorientasi objek.

Sederhananya, ini menggunakan properti bersama dan nilai uniknya untuk secara jelas menunjukkan skema spesifik mana dalam daftar oneOf atau anyOf yang harus digunakan.

Misalnya, di toko hewan peliharaan, kita perlu menggunakan skema untuk mendeskripsikan hewan peliharaan. (Dan kucing serta anjing memiliki properti yang berbeda.)

Skema untuk anjing adalah:

{

    "name": "Hotdog",

    "age": 3,

    "weight": 25.5,

    "petType": "dog",

    "breed": "Golden Retriever",

    "isVaccinated": true,

    "walkingSchedule": "Morning and Evening",

    "favoriteToys": ["Frisbee", "Tennis Ball"],

    "trainingLevel": "Intermediate"

}

Skema untuk kucing adalah:

{

    "name": "Meow",

    "age": 2,

    "weight": 4.2,

    "petType": "cat",

    "isVaccinated": true,

    "isIndoor": true,

    "litterBoxType": "Enclosed",

    "scratchingPostHeight": 120,

    "favoriteSleepingSpot": "Balcony"

}

Seperti yang Anda lihat, meskipun kedua skema memiliki bidang umum seperti petType, name, age, dll., anjing memiliki bidang spesifik seperti breed, walkingSchedule, dll., sedangkan kucing memiliki bidang spesifik seperti isIndoor, litterBoxType, dll.

Jika Anda hanya menggunakan oneOf untuk mendefinisikan skema ini saat merancang dokumentasi API Anda, dokumentasi tersebut secara teknis dapat membedakan antara skema dog dan cat. Namun, korespondensi setiap jenis tidak terlalu jelas. Pembaca harus beralih di antara dua tab skema untuk membandingkannya, yang menjadi membingungkan ketika ada banyak parameter.

gunakan oneOf untuk mendefinisikan beberapa skema

Dengan menambahkan discriminator, dokumentasi akan menampilkan menu dropdown, di mana pembaca dapat memilih nilai petType (dog atau cat). Setelah dipilih, halaman secara otomatis menampilkan skema yang benar dengan bidang yang relevan. Ini menghilangkan kebutuhan untuk membandingkan beberapa tab dan membuat perbedaan antara setiap skema jauh lebih jelas.

Sebuah discriminator biasanya digunakan bersama dengan oneOf atau anyOf. oneOf mendefinisikan skema objek yang mungkin, dan discriminator memberi tahu parser bagaimana menentukan skema mana yang akan diterapkan berdasarkan jenis yang dipilih.

Ini membuat objek kompleks lebih jelas dan membantu alat secara otomatis membedakan jenis saat merender dokumentasi atau menghasilkan kode.

Properti Konfigurasi `discriminator`

Sebuah discriminator berisi dua properti utama:

propertyName: Menentukan nama bidang yang digunakan untuk membedakan jenis, seperti petType dalam contoh di atas.
mapping: Mendefinisikan hubungan pemetaan antara nilai bidang dan skema spesifik, seperti "dog" yang sesuai dengan skema anjing dan "cat" yang sesuai dengan skema kucing.

Contoh konfigurasi di OpenAPI:

discriminator:
  propertyName: petType
  mapping:
    dog: '#/components/schemas/Dog'
    cat: '#/components/schemas/Cat'

Mengonfigurasi Discriminator di Apidog

Apidog mendukung konfigurasi discriminator dengan dua cara:

GUI + Skema JSON
Mengimpor spesifikasi OpenAPI secara langsung

Metode 1: GUI + Skema JSON

Pertama, buat skema di Apidog, seperti Dog dan Cat:

Buka endpoint tempat Anda ingin menggunakan skema ini dan buka editor body permintaan atau respons.

Pilih bidang yang ingin Anda definisikan sebagai komposisi skema dan pilih Advanced Settings → Schema Compositions → oneOf.

Dalam oneOf, referensikan skema yang Anda butuhkan, seperti Dog dan Cat.

mereferensikan skema untuk komposisi skema oneOf

Sekarang Anda telah mendefinisikan beberapa skema yang mungkin melalui oneOf. Selanjutnya, Anda perlu menambahkan discriminator untuk menentukan cara membedakan skema ini. Klik JSON Schema untuk beralih ke mode kode:

Tambahkan konfigurasi discriminator di lokasi yang sesuai (pada tingkat yang sama dengan oneOf), misalnya:

"discriminator": {
    "propertyName": "petType",
    "mapping": {
        "dog": "#/definitions/190704823",
        "cat": "#/definitions/190704706"
    }
}

Nilai-nilai dalam mapping, seperti #/definitions/190704823, adalah ID unik yang dihasilkan secara internal oleh Apidog untuk skema. Anda dapat menemukan jalur definitions yang sesuai untuk setiap skema di panel konfigurasi Skema JSON.

Setelah konfigurasi selesai, simpan. Dalam dokumentasi API, Anda dapat secara cerdas beralih jenis objek berdasarkan nilai bidang petType.

Metode 2: Mengimpor Spesifikasi OpenAPI Secara Langsung

Ini adalah pendekatan yang lebih standar, terutama cocok untuk tim yang terbiasa dengan alur kerja "design-first".

Tulis spesifikasi OpenAPI Anda dengan discriminator disertakan, lalu impor ke Apidog.

Misalnya, dalam spesifikasi OpenAPI, definisi discriminator adalah sebagai berikut:

Pet:
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      cat: '#/components/schemas/Cat'

Definisi ini dengan jelas menyatakan:

Melalui oneOf, tentukan bahwa objek mungkin bertipe Dog atau Cat
Melalui discriminator, tentukan jenis spesifik berdasarkan nilai bidang petType
Melalui mapping, tentukan dengan jelas bahwa "dog" sesuai dengan skema Dog dan "cat" sesuai dengan skema Cat.

Spesifikasi OpenAPI lengkap adalah sebagai berikut:

openapi: 3.0.3
info:
  title: Pet Shop API
  version: 1.0.0

components:
  schemas:
    Dog:
      type: object
      properties:
        petType:
          type: string
          enum: [dog]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        breed:
          type: string
        isVaccinated:
          type: boolean
        walkingSchedule:
          type: string
        favoriteToys:
          type: array
          items:
            type: string
        trainingLevel:
          type: string
      required:
        - petType
        - name
        - age

    Cat:
      type: object
      properties:
        petType:
          type: string
          enum: [cat]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        isVaccinated:
          type: boolean
        isIndoor:
          type: boolean
        litterBoxType:
          type: string
        scratchingPostHeight:
          type: integer
        favoriteSleepingSpot:
          type: string
      required:
        - petType
        - name
        - age

    Pet:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'
      discriminator:
        propertyName: petType
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'

paths:
  /pets:
    get:
      summary: Get pet information
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

Setelah menyelesaikan spesifikasi OpenAPI, gunakan fitur import di Apidog. Apidog akan mengurai semua spesifikasi, secara otomatis membuat skema dan endpoint yang sesuai, dan dengan benar mengenali konfigurasi discriminator (enum ditambahkan di sini untuk mengunci nilai parameter).

mengimpor OpenAPI untuk menambahkan discriminator untuk membedakan beberapa skema

FAQ

1. Kapan Menggunakan Discriminator?

Anda harus menggunakan discriminator hanya ketika endpoint Anda sudah menyertakan bidang yang mengidentifikasi skema. Dalam contoh di atas, bidang petType ada dalam desain API dan digunakan untuk membedakan antara jenis hewan peliharaan.

discriminator hanya memberi tahu alat bagaimana memilih skema yang benar berdasarkan nilai bidang tersebut.

Jika endpoint Anda tidak menyertakan bidang pengidentifikasi jenis tersebut, maka discriminator tidak tepat—menggunakan oneOf saja sudah cukup.

Juga, jika skema Anda sederhana atau hanya memiliki sedikit variasi, Anda mungkin tidak memerlukan discriminator sama sekali.

2. Haruskah Discriminator Digunakan dengan oneOf?

Ya. Sebuah discriminator harus digunakan bersama dengan oneOf, anyOf, atau allOf. Ini tidak dapat mendefinisikan skema sendiri—ini hanya menjelaskan bagaimana membedakan antara beberapa skema yang mungkin.

Kesimpulan

discriminator adalah fitur opsional dalam spesifikasi OpenAPI yang digunakan untuk meningkatkan pengalaman pengguna dari oneOf/anyOf/allOf.

Ketika spesifikasi endpoint Anda sudah berisi bidang yang digunakan untuk mengidentifikasi jenis, Anda dapat mengonfigurasi discriminator di Apidog untuk membuat dokumentasi API lebih jelas dan lebih cerdas.

Tentu saja, jika Anda merasa konfigurasi merepotkan atau skema relatif sederhana, Anda dapat sepenuhnya hanya menggunakan komposisi skema seperti oneOf.