Apidog ile API Tasarımında Farklı Parametre Yapılarını Türe Göre Eşleştirmek için Discriminator Kullanımı

Önceki makalemiz "API Birden Fazla Parametre Yapısına Sahip Olduğunda Ne Yapmalı?" başlıklı yazımızda, bir API'nin farklı parametre yapıları gerektirdiğinde, bunları Apidog'da tanımlamak için oneOf, anyOf veya allOf kullanabileceğinizi tartıştık.

Bu şema bileşimlerini kullanarak parametre yapılarını ayarladıktan ve parametreleriniz veri türünü tanımlayan bir alan içerdiğinde, şemalar arasında daha sezgisel bir ayrım yapmak için OpenAPI spesifikasyonundaki discriminator özelliğini kullanarak dokümantasyonu daha da netleştirebilirsiniz.

Discriminator Nedir?

OpenAPI'de discriminator'ın rolü, nesne yönelimli programlamadan "polimorfizmi" uygulamaktır.

Basitçe söylemek gerekirse, oneOf veya anyOf listesindeki hangi belirli şemanın kullanılması gerektiğini açıkça belirtmek için paylaşılan bir özelliği ve onun benzersiz değerini kullanır.

Örneğin, bir evcil hayvan mağazasında, evcil hayvanları tanımlamak için bir şema kullanmamız gerekiyor. (Ve kedilerin ve köpeklerin farklı özellikleri var.)

Köpekler için şema şöyledir:

{

    "name": "Hotdog",

    "age": 3,

    "weight": 25.5,

    "petType": "dog",

    "breed": "Golden Retriever",

    "isVaccinated": true,

    "walkingSchedule": "Morning and Evening",

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

    "trainingLevel": "Intermediate"

}

Kediler için şema şöyledir:

{

    "name": "Meow",

    "age": 2,

    "weight": 4.2,

    "petType": "cat",

    "isVaccinated": true,

    "isIndoor": true,

    "litterBoxType": "Enclosed",

    "scratchingPostHeight": 120,

    "favoriteSleepingSpot": "Balcony"

}

Gördüğünüz gibi, her iki şema da petType, name, age gibi ortak alanlara sahip olsa da, köpeklerin breed, walkingSchedule gibi belirli alanları varken, kedilerin isIndoor, litterBoxType gibi belirli alanları vardır.

API dokümantasyonunuzu tasarlarken bu şemaları tanımlamak için yalnızca oneOf kullanırsanız, dokümantasyon teknik olarak dog ve cat şemalarını ayırt edebilir. Ancak, her türün karşılığı pek net değildir. Okuyucuların, çok sayıda parametre olduğunda kafa karıştırıcı hale gelen iki şema sekmesi arasında karşılaştırma yapmak için geçiş yapması gerekir.

birden fazla şemayı tanımlamak için oneOf kullanın

Bir discriminator ekleyerek, dokümantasyon bir açılır menü gösterecektir; burada okuyucular petType değerini (dog veya cat) seçebilirler. Seçildikten sonra, sayfa ilgili alanlarla birlikte doğru şemayı otomatik olarak görüntüler. Bu, birden fazla sekmeyi karşılaştırma ihtiyacını ortadan kaldırır ve her şema arasındaki farkları çok daha net hale getirir.

şemaları daha net hale getiren discriminator

Bir discriminator tipik olarak oneOf veya anyOf ile birlikte kullanılır. oneOf olası nesne şemalarını tanımlar ve discriminator, ayrıştırıcıya seçilen türe göre hangi şemanın uygulanacağını nasıl belirleyeceğini söyler.

Bu, karmaşık nesneleri daha net hale getirir ve araçların dokümantasyonu oluştururken veya kod üretirken türleri otomatik olarak ayırt etmesine yardımcı olur.

`discriminator` Yapılandırma Özellikleri

Bir discriminator iki temel özellik içerir:

propertyName: Türleri ayırt etmek için kullanılan alan adını belirtir, yukarıdaki örnekte petType gibi.
mapping: Alan değerleri ile belirli şemalar arasındaki eşleme ilişkisini tanımlar, örneğin "dog" köpek şemasına ve "cat" kedi şemasına karşılık gelir.

OpenAPI'de yapılandırma örneği:

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

Apidog'da Discriminator Yapılandırma

Apidog, discriminator'ı iki şekilde yapılandırmayı destekler:

GUI + JSON Şeması
OpenAPI spesifikasyonlarını doğrudan içe aktarma

Yöntem 1: GUI + JSON Şeması

İlk olarak, Apidog'da Dog ve Cat gibi şemaları oluşturun:

Bu şemaları kullanmak istediğiniz uç noktayı açın ve istek veya yanıt gövdesi düzenleyicisine gidin.

Şema bileşimi olarak tanımlamak istediğiniz alanı seçin ve Gelişmiş Ayarlar → Şema Bileşimleri → oneOf seçeneğini belirleyin.

oneOf içinde, Dog ve Cat gibi ihtiyacınız olan şemaları referans alın.

oneOf şema bileşimleri için şemaları referans alma

Şimdi oneOf aracılığıyla birden fazla olası şema tanımladınız. Ardından, bu şemaları nasıl ayırt edeceğinizi belirtmek için discriminator eklemeniz gerekir. Kod moduna geçmek için JSON Şeması'na tıklayın:

Uygun konuma (oneOf ile aynı seviyede) discriminator yapılandırmasını ekleyin, örneğin:

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

mapping içindeki değerler, örneğin #/definitions/190704823, Apidog tarafından şemalar için dahili olarak oluşturulan benzersiz kimliklerdir. Her şema için ilgili definitions yolunu JSON Şema yapılandırma panelinde bulabilirsiniz.

Yapılandırma tamamlandıktan sonra kaydedin. API dokümantasyonunda, petType alanının değerine göre nesne türlerini akıllıca değiştirebilirsiniz.

Yöntem 2: OpenAPI Spesifikasyonlarını Doğrudan İçe Aktarma

Bu, özellikle "önce tasarım" iş akışlarına alışkın ekipler için daha standart bir yaklaşımdır.

discriminator dahil olmak üzere OpenAPI spesifikasyonlarınızı yazın, ardından Apidog'a aktarın.

Örneğin, OpenAPI spesifikasyonlarında discriminator'ın tanımı şöyledir:

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

Bu tanım açıkça belirtir:

oneOf aracılığıyla, nesnenin Dog veya Cat türünde olabileceğini belirtir
discriminator aracılığıyla, belirli türü petType alanının değerine göre belirlemeyi belirtir
mapping aracılığıyla, "dog"'un Dog şemasına ve "cat"'in Cat şemasına karşılık geldiğini açıkça belirtir.

Tam OpenAPI spesifikasyonları şöyledir:

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'

OpenAPI spesifikasyonlarını tamamladıktan sonra, Apidog'daki içe aktar özelliğini kullanın. Apidog tüm spesifikasyonları ayrıştıracak, otomatik olarak ilgili şemaları ve uç noktaları oluşturacak ve discriminator yapılandırmasını doğru bir şekilde tanıyacaktır (parametre değerlerini kilitlemek için buraya enum eklenmiştir).

birden fazla şemayı ayırt etmek için discriminator eklemek üzere OpenAPI'yi içe aktarma

Sıkça Sorulan Sorular

1. Discriminator Ne Zaman Kullanılmalı?

Bir discriminator'ı yalnızca uç noktanız zaten şemaları tanımlayan bir alan içerdiğinde kullanmalısınız. Yukarıdaki örnekte, petType alanı API tasarımında mevcuttur ve evcil hayvan türleri arasında ayrım yapmak için kullanılır.

discriminator, araçlara o alanın değerine göre doğru şemayı nasıl seçeceklerini söyler.

Uç noktanız böyle bir tür tanımlayıcı alan içermiyorsa, o zaman bir discriminator uygun değildir - yalnızca oneOf kullanmak yeterlidir.

Ayrıca, şemanız basitse veya sadece birkaç varyasyona sahipse, bir discriminator'a hiç ihtiyacınız olmayabilir.

2. Discriminator, oneOf ile Birlikte Kullanılmalı mı?

Evet. Bir discriminator, oneOf, anyOf veya allOf ile birlikte kullanılmalıdır. Kendi başına şemaları tanımlayamaz - yalnızca birden fazla olası şema arasında nasıl ayrım yapılacağını açıklar.

Sonuç

discriminator, oneOf/anyOf/allOf'un kullanıcı deneyimini geliştirmek için kullanılan OpenAPI spesifikasyonunda isteğe bağlı bir özelliktir.

Uç nokta spesifikasyonlarınız zaten türleri tanımlamak için kullanılan alanları içerdiğinde, API dokümantasyonunu daha net ve daha akıllı hale getirmek için Apidog'da discriminator'ı yapılandırabilirsiniz.

Elbette, yapılandırmayı zahmetli buluyorsanız veya şema nispeten basitse, yalnızca oneOf gibi şema bileşimini tamamen kullanabilirsiniz.