Perubahan OpenAPI 3.2 vs 3.1 vs 3.0: Apa yang Berbeda?

Intinya

OpenAPI 3.1 menambahkan kompatibilitas JSON Schema penuh, webhook, dan peningkatan diskriminator. OpenAPI 3.2 menambahkan dukungan metode QUERY, contoh yang ditingkatkan, dan definisi keamanan yang lebih baik. Modern PetstoreAPI menggunakan OpenAPI 3.2 untuk mendemonstrasikan semua fitur terbaru dengan contoh siap produksi.

Pendahuluan

Anda sedang menulis spesifikasi OpenAPI. Anda melihat referensi ke OpenAPI 3.0, 3.1, dan 3.2. Apa perbedaannya? Haruskah Anda meningkatkan versi? Akankah alat Anda mendukung versi baru?

OpenAPI telah berkembang secara signifikan dari 3.0 ke 3.2. Setiap versi menambahkan fitur yang membuat spesifikasi API lebih kuat dan akurat. Namun tidak semua alat mendukung versi terbaru, menciptakan tantangan kompatibilitas.

Swagger Petstore yang lama menggunakan OpenAPI 2.0 (spesifikasi Swagger). Modern PetstoreAPI menggunakan OpenAPI 3.2, menampilkan setiap fitur baru dengan contoh siap produksi.

💡

Jika Anda membangun atau menguji REST API, Apidog mendukung OpenAPI 3.0, 3.1, dan 3.2. Anda dapat mengimpor spesifikasi, memvalidasi terhadap skema, dan menguji implementasi API Anda. Apidog membantu Anda memahami versi mana yang akan digunakan dan cara bermigrasi.

button

Dalam panduan ini, Anda akan mempelajari apa yang berubah di setiap versi OpenAPI, cara memilih versi yang tepat, dan bagaimana Modern PetstoreAPI mendemonstrasikan fitur OpenAPI 3.2.

Dasar OpenAPI 3.0

OpenAPI 3.0 (dirilis Juli 2017) adalah peningkatan besar dari Swagger 2.0.

Fitur Utama

1. Beberapa server

servers:
  - url: https://api.petstoreapi.com/v1
    description: Production
  - url: https://staging.petstoreapi.com/v1
    description: Staging

Swagger 2.0 hanya mendukung satu host.

2. Objek badan permintaan (Request body object)

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'

Lebih jelas daripada parameter body Swagger 2.0.

3. Komponen untuk penggunaan ulang (reusability)

components:
  schemas:
    Pet:
      type: object
  responses:
    NotFound:
      description: Resource not found
  parameters:
    PetId:
      name: petId
      in: path

Organisasi yang lebih baik daripada definitions Swagger 2.0.

4. Callback

Definisikan callback asinkron (webhook):

callbacks:
  orderUpdate:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderUpdate'

5. Tautan

Definisikan hubungan antar operasi:

links:
  GetPetByPetId:
    operationId: getPetById
    parameters:
      petId: '$response.body#/id'

Keterbatasan

1. Ketidakcocokan JSON Schema

OpenAPI 3.0 menggunakan subset JSON Schema Draft 5, bukan JSON Schema penuh. Ini menyebabkan masalah validasi.

2. Tidak ada objek webhook

Webhook didefinisikan sebagai callback, yang membingungkan.

3. Diskriminator terbatas

Dukungan polimorfisme masih dasar.

4. Tidak ada tipe null

Anda tidak dapat secara langsung menentukan type: null.

Perubahan Besar OpenAPI 3.1

OpenAPI 3.1 (dirilis Februari 2021) berfokus pada keselarasan JSON Schema.

1. Kompatibilitas Penuh JSON Schema 2020-12

Perubahan terbesar: Skema OpenAPI 3.1 adalah JSON Schema 2020-12 yang valid.

Sebelumnya (OpenAPI 3.0):

type: string
nullable: true  # OpenAPI-specific

Setelahnya (OpenAPI 3.1):

type: [string, "null"]  # Standard JSON Schema

Manfaat:

Gunakan validator JSON Schema apa pun
Bagikan skema antara OpenAPI dan alat lainnya
Akses ke fitur JSON Schema penuh

2. Objek Webhook

Sebelumnya (OpenAPI 3.0):

# Webhooks defined as callbacks (confusing)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # webhook definition

Setelahnya (OpenAPI 3.1):

webhooks:
  orderUpdate:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'

Pemisahan yang lebih jelas antara endpoint API dan webhook.

3. Peningkatan Diskriminator

Dukungan polimorfisme yang lebih baik:

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

4. Pengidentifikasi Lisensi Objek Info

info:
  license:
    name: MIT
    identifier: MIT  # SPDX identifier

5. PathItem $ref

Referensi item jalur (path item) lengkap:

paths:
  /pets:
    $ref: '#/components/pathItems/PetsCollection'

Perubahan yang Merusak (Breaking Changes)

1. nullable dihapusGunakan type: [string, "null"] sebagai gantinya.
2. exclusiveMinimum/exclusiveMaximum berubahSekarang boolean, bukan numerik.
3. example vs examplesValidasi yang lebih ketat.

Fitur Terbaru OpenAPI 3.2

OpenAPI 3.2 (dirilis TBD, draf tersedia) menambahkan pola API modern.

1. Dukungan Metode QUERY

Metode HTTP QUERY untuk pencarian kompleks:

paths:
  /pets/search:
    query:  # New method
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: Search results

Modern PetstoreAPI menggunakan QUERY untuk pencarian hewan peliharaan yang kompleks.

2. Contoh yang Ditingkatkan

Beberapa contoh dengan metadata:

examples:
  availableCat:
    summary: Available cat
    description: A cat available for adoption
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: Adopted dog
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. Definisi Keamanan yang Ditingkatkan

Dukungan OAuth 2.0 yang lebih baik:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://petstoreapi.com/oauth/authorize
          tokenUrl: https://petstoreapi.com/oauth/token
          refreshUrl: https://petstoreapi.com/oauth/refresh
          scopes:
            pets:read: Read pets
            pets:write: Create and update pets
            orders:read: Read orders

4. Peningkatan Pemetaan Diskriminator

Polimorfisme yang lebih fleksibel:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Can mix local and $ref

5. Dukungan Deprecasi yang Lebih Baik

Deprecate bidang tertentu:

properties:
  oldField:
    type: string
    deprecated: true
    description: Use newField instead
  newField:
    type: string

Bagaimana Modern PetstoreAPI Menggunakan OpenAPI 3.2

Modern PetstoreAPI menampilkan setiap fitur OpenAPI 3.2.

1. Spesifikasi Lengkap

Spesifikasi OpenAPI 3.2 lengkap tersedia di:

https://petstoreapi.com/openapi.json

2. Metode QUERY untuk Pencarian Kompleks

/pets/search:
  query:
    summary: Search pets with complex criteria
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. Webhook

webhooks:
  petStatusChanged:
    post:
      summary: Pet status changed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. Skema Polimorfik

Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Bird'
  discriminator:
    propertyName: species

5. Contoh Komprehensif

Setiap endpoint menyertakan beberapa contoh yang menunjukkan skenario berbeda.

6. Respons Kesalahan RFC 9457

responses:
  '400':
    description: Bad Request
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

Lihat spesifikasi OpenAPI lengkap untuk semua fitur.

Panduan Migrasi

3.0 ke 3.1

1. Ganti nullable:

# Before
type: string
nullable: true

# After
type: [string, "null"]

2. Perbarui exclusiveMinimum/exclusiveMaximum:

# Before
minimum: 0
exclusiveMinimum: true

# After
minimum: 0
exclusiveMinimum: 0

3. Pindahkan webhook:

# Before
paths:
  /subscribe:
    callbacks:
      # webhook

# After
webhooks:
  # webhook

3.1 ke 3.2

1. Tambahkan metode QUERY jika sesuai:

/pets/search:
  query:  # New in 3.2
    # complex search

2. Tingkatkan contoh:

examples:
  example1:
    summary: Description
    value: {...}

3. Perbarui definisi keamanan:

Tambahkan refreshUrl ke alur OAuth.

Menguji Spesifikasi OpenAPI dengan Apidog

Apidog mendukung semua versi OpenAPI.

Impor Spesifikasi OpenAPI

1. Buka Apidog
2. Klik "Impor"
3. Pilih "OpenAPI 3.x"
4. Tempel URL atau unggah file
5. Apidog memvalidasi dan mengimpor

Validasi Spesifikasi

Apidog memeriksa:

Validitas skema
Integritas referensi
Kebenaran contoh
Kelengkapan definisi keamanan

Uji Implementasi API

Buat kasus uji dari spesifikasi:

Validasi permintaan
Validasi respons
Pemeriksaan kode status
Kepatuhan skema

Perbandingan Versi

Impor beberapa versi dan bandingkan:

Perubahan yang merusak
Endpoint baru
Perubahan skema
Bidang yang tidak digunakan lagi (deprecated)

Kesimpulan

OpenAPI telah berkembang secara signifikan:

OpenAPI 3.0: Fondasi dengan server, badan permintaan, callback
OpenAPI 3.1: Kompatibilitas JSON Schema, objek webhook, polimorfisme yang lebih baik
OpenAPI 3.2: Metode QUERY, contoh yang ditingkatkan, keamanan yang lebih baik

Modern PetstoreAPI menggunakan OpenAPI 3.2 untuk mendemonstrasikan semua fitur dengan contoh siap produksi. Ini adalah implementasi referensi untuk desain API modern.

Gunakan Apidog untuk bekerja dengan versi OpenAPI apa pun, memvalidasi spesifikasi, dan menguji implementasi.

FAQ

Haruskah saya meningkatkan versi ke OpenAPI 3.1 atau 3.2?

Jika alat Anda mendukungnya, ya. Kompatibilitas JSON Schema OpenAPI 3.1 sangat berharga. OpenAPI 3.2 menambahkan pola modern seperti metode QUERY.

Apakah spesifikasi OpenAPI 3.0 saya akan berfungsi dengan alat 3.1?

Sebagian besar, tetapi nullable dan exclusiveMinimum/exclusiveMaximum memerlukan pembaruan.

Apakah generator kode mendukung OpenAPI 3.2?

Dukungan semakin berkembang. Periksa dokumentasi generator Anda. Banyak yang mendukung 3.1, lebih sedikit yang mendukung 3.2.

Bisakah saya menggunakan fitur OpenAPI 3.2 di 3.1?

Tidak. Gunakan versi yang sesuai dengan fitur Anda. Jika Anda memerlukan metode QUERY, gunakan 3.2.

Bagaimana cara memvalidasi spesifikasi OpenAPI saya?

Gunakan Apidog untuk mengimpor dan memvalidasi spesifikasi Anda. Ini memeriksa validitas skema dan integritas referensi.

Di mana saya bisa melihat contoh lengkap OpenAPI 3.2?

Modern PetstoreAPI menyediakan spesifikasi OpenAPI 3.2 yang lengkap dan siap produksi.

Apa perbedaan antara webhook dan callback?

Webhook adalah permintaan HTTP dari server ke klien. Callback didefinisikan dalam OpenAPI 3.0 sebagai bagian dari operasi. OpenAPI 3.1+ memiliki objek webhooks khusus.

Haruskah saya menggunakan JSON atau YAML untuk spesifikasi OpenAPI?

Keduanya berfungsi. YAML lebih mudah dibaca oleh manusia. JSON lebih mudah untuk alat. Modern PetstoreAPI menyediakan kedua format.