OpenAPI 3.2 เทียบกับ 3.1 และ 3.0: มีอะไรเปลี่ยนแปลงบ้าง

สรุป

OpenAPI 3.1 เพิ่มความเข้ากันได้กับ JSON Schema อย่างสมบูรณ์, webhooks และการปรับปรุง discriminator OpenAPI 3.2 เพิ่มการรองรับเมธอด QUERY, ตัวอย่างที่ปรับปรุงดีขึ้น และการกำหนดค่าความปลอดภัยที่ดีขึ้น Modern PetstoreAPI ใช้ OpenAPI 3.2 เพื่อแสดงคุณสมบัติล่าสุดทั้งหมดด้วยตัวอย่างที่พร้อมใช้งานจริง

บทนำ

คุณกำลังเขียน OpenAPI specification คุณเห็นการอ้างอิงถึง OpenAPI 3.0, 3.1 และ 3.2 แตกต่างกันอย่างไร? คุณควรอัปเกรดหรือไม่? เครื่องมือของคุณจะรองรับเวอร์ชันใหม่หรือไม่?

OpenAPI มีการพัฒนาอย่างมีนัยสำคัญจาก 3.0 เป็น 3.2 แต่ละเวอร์ชันเพิ่มคุณสมบัติที่ทำให้ API specifications มีประสิทธิภาพและแม่นยำยิ่งขึ้น แต่ไม่ใช่ทุกเครื่องมือที่รองรับเวอร์ชันล่าสุด ซึ่งก่อให้เกิดความท้าทายด้านความเข้ากันได้

Swagger Petstore รุ่นเก่าใช้ OpenAPI 2.0 (Swagger specification) Modern PetstoreAPI ใช้ OpenAPI 3.2 ซึ่งแสดงให้เห็นคุณสมบัติใหม่ทุกอย่างพร้อมตัวอย่างที่พร้อมใช้งานจริง

ในคู่มือนี้ คุณจะได้เรียนรู้การเปลี่ยนแปลงในแต่ละเวอร์ชันของ OpenAPI, วิธีเลือกเวอร์ชันที่เหมาะสม และวิธีที่ Modern PetstoreAPI แสดงให้เห็นคุณสมบัติของ OpenAPI 3.2

พื้นฐาน OpenAPI 3.0

OpenAPI 3.0 (เปิดตัวในเดือนกรกฎาคม 2017) เป็นการอัปเกรดครั้งใหญ่จาก Swagger 2.0

คุณสมบัติหลัก

1. เซิร์ฟเวอร์หลายแห่ง

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

Swagger 2.0 รองรับโฮสต์เดียวเท่านั้น

2. ออบเจกต์เนื้อหาคำขอ (Request body object)

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

ชัดเจนกว่าพารามิเตอร์ body ของ Swagger 2.0

3. Components เพื่อการนำกลับมาใช้ใหม่

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

จัดระเบียบได้ดีกว่า definitions ของ Swagger 2.0

4. Callbacks

กำหนด asynchronous callbacks (webhooks):

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

5. Links

กำหนดความสัมพันธ์ระหว่างการดำเนินการ:

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

ข้อจำกัด

1. ความไม่เข้ากันกับ JSON Schema

OpenAPI 3.0 ใช้ส่วนย่อยของ JSON Schema Draft 5 ไม่ใช่ JSON Schema แบบเต็ม ซึ่งทำให้เกิดปัญหาในการตรวจสอบความถูกต้อง

2. ไม่มีออบเจกต์ webhooks

Webhooks ถูกกำหนดเป็น callbacks ซึ่งสร้างความสับสน

3. Discriminator ที่จำกัด

การรองรับ Polymorphism เป็นแบบพื้นฐาน

4. ไม่มีชนิดข้อมูล null

คุณไม่สามารถระบุ type: null โดยตรงได้

การเปลี่ยนแปลงหลักใน OpenAPI 3.1

OpenAPI 3.1 (เปิดตัวในเดือนกุมภาพันธ์ 2021) มุ่งเน้นไปที่การจัดเรียง JSON Schema

1. ความเข้ากันได้กับ JSON Schema 2020-12 อย่างสมบูรณ์

การเปลี่ยนแปลงที่ใหญ่ที่สุด: OpenAPI 3.1 schemas เป็น JSON Schema 2020-12 ที่ถูกต้อง

ก่อนหน้า (OpenAPI 3.0):

type: string
nullable: true  # เฉพาะของ OpenAPI

หลังจาก (OpenAPI 3.1):

type: [string, "null"]  # JSON Schema มาตรฐาน

ประโยชน์:

• ใช้ JSON Schema validator ใดก็ได้
• แชร์ schemas ระหว่าง OpenAPI และเครื่องมืออื่นๆ
• เข้าถึงคุณสมบัติ JSON Schema แบบเต็ม

2. ออบเจกต์ Webhooks

ก่อนหน้า (OpenAPI 3.0):

# Webhooks ถูกกำหนดเป็น callbacks (สร้างความสับสน)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # การกำหนด webhook

หลังจาก (OpenAPI 3.1):

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

การแยกส่วนที่ชัดเจนยิ่งขึ้นระหว่าง API endpoints และ webhooks

3. การปรับปรุง Discriminator

การรองรับ polymorphism ที่ดีขึ้น:

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

4. ตัวระบุสิทธิ์ใช้งานของ Info Object

info:
  license:
    name: MIT
    identifier: MIT  # ตัวระบุ SPDX

5. PathItem $ref

อ้างอิงถึง Path Item ทั้งหมด:

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

การเปลี่ยนแปลงที่ส่งผลกระทบ

1. ลบ nullable ออก

ให้ใช้ type: [string, "null"] แทน

2. exclusiveMinimum/exclusiveMaximum เปลี่ยนแปลง

ตอนนี้เป็น boolean ไม่ใช่ตัวเลข

3. example เทียบกับ examples

การตรวจสอบความถูกต้องที่เข้มงวดขึ้น

คุณสมบัติล่าสุดของ OpenAPI 3.2

OpenAPI 3.2 (เปิดตัว TBD, มีฉบับร่าง) เพิ่มรูปแบบ API ที่ทันสมัย

1. การรองรับเมธอด QUERY

เมธอด HTTP QUERY สำหรับการค้นหาที่ซับซ้อน:

paths:
  /pets/search:
    query:  # เมธอดใหม่
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: ผลการค้นหา

Modern PetstoreAPI ใช้ QUERY สำหรับการค้นหาสัตว์เลี้ยงที่ซับซ้อน

2. ตัวอย่างที่ปรับปรุงดีขึ้น

หลายตัวอย่างพร้อมข้อมูลเมตา:

examples:
  availableCat:
    summary: แมวที่พร้อมจำหน่าย
    description: แมวที่พร้อมสำหรับการรับเลี้ยง
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: สุนัขที่ได้รับการรับเลี้ยง
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. การกำหนดค่าความปลอดภัยที่ปรับปรุงใหม่

การรองรับ OAuth 2.0 ที่ดีขึ้น:

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: อ่านข้อมูลสัตว์เลี้ยง
            pets:write: สร้างและอัปเดตข้อมูลสัตว์เลี้ยง
            orders:read: อ่านข้อมูลคำสั่งซื้อ

4. การปรับปรุงการแมป Discriminator

Polymorphism ที่ยืดหยุ่นมากขึ้น:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # สามารถผสมระหว่าง local และ $ref

5. การรองรับการเลิกใช้งานที่ดีขึ้น

เลิกใช้งานฟิลด์ที่เฉพาะเจาะจง:

properties:
  oldField:
    type: string
    deprecated: true
    description: ให้ใช้ newField แทน
  newField:
    type: string

Modern PetstoreAPI ใช้งาน OpenAPI 3.2 อย่างไร

Modern PetstoreAPI แสดงให้เห็นคุณสมบัติทุกอย่างของ OpenAPI 3.2

1. Specification ฉบับสมบูรณ์

OpenAPI 3.2 spec ฉบับสมบูรณ์สามารถดูได้ที่:

https://petstoreapi.com/openapi.json

2. เมธอด QUERY สำหรับการค้นหาที่ซับซ้อน

/pets/search:
  query:
    summary: ค้นหาสัตว์เลี้ยงด้วยเกณฑ์ที่ซับซ้อน
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. Webhooks

webhooks:
  petStatusChanged:
    post:
      summary: สถานะสัตว์เลี้ยงมีการเปลี่ยนแปลง
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. Polymorphic Schemas

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

5. ตัวอย่างที่ครอบคลุม

ทุก endpoint มีตัวอย่างหลายรูปแบบเพื่อแสดงสถานการณ์ที่แตกต่างกัน

6. การตอบกลับข้อผิดพลาดตาม RFC 9457

responses:
  '400':
    description: คำขอไม่ถูกต้อง
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

ดู OpenAPI spec ฉบับสมบูรณ์ สำหรับคุณสมบัติทั้งหมด

คู่มือการย้ายข้อมูล

3.0 ไป 3.1

1. แทนที่ nullable:

# ก่อนหน้า
type: string
nullable: true

# หลังจาก
type: [string, "null"]

2. อัปเดต exclusiveMinimum/exclusiveMaximum:

# ก่อนหน้า
minimum: 0
exclusiveMinimum: true

# หลังจาก
minimum: 0
exclusiveMinimum: 0

3. ย้าย webhooks:

# ก่อนหน้า
paths:
  /subscribe:
    callbacks:
      # webhook

# หลังจาก
webhooks:
  # webhook

3.1 ไป 3.2

1. เพิ่มเมธอด QUERY ในจุดที่เหมาะสม:

/pets/search:
  query:  # ใหม่ในเวอร์ชัน 3.2
    # การค้นหาที่ซับซ้อน

2. ปรับปรุงตัวอย่าง:

examples:
  example1:
    summary: คำอธิบาย
    value: {...}

3. อัปเดตคำจำกัดความด้านความปลอดภัย:

เพิ่ม refreshUrl ไปยัง OAuth flows

การทดสอบ OpenAPI Specs ด้วย Apidog

Apidog รองรับ OpenAPI ทุกเวอร์ชัน

นำเข้า OpenAPI Spec

1. เปิด Apidog
2. คลิก "Import"
3. เลือก "OpenAPI 3.x"
4. วาง URL หรืออัปโหลดไฟล์
5. Apidog ตรวจสอบความถูกต้องและนำเข้า

ตรวจสอบความถูกต้องของ Spec

Apidog ตรวจสอบ:

• ความถูกต้องของ Schema
• ความสมบูรณ์ของการอ้างอิง
• ความถูกต้องของตัวอย่าง
• ความสมบูรณ์ของคำจำกัดความด้านความปลอดภัย

ทดสอบการใช้งาน API

สร้าง test cases จาก spec:

• การตรวจสอบความถูกต้องของ Request
• การตรวจสอบความถูกต้องของ Response
• การตรวจสอบรหัสสถานะ
• การปฏิบัติตาม Schema

การเปรียบเทียบเวอร์ชัน

นำเข้าหลายเวอร์ชันและเปรียบเทียบ:

• การเปลี่ยนแปลงที่ส่งผลกระทบ
• Endpoints ใหม่
• การเปลี่ยนแปลง Schema
• ฟิลด์ที่เลิกใช้งานแล้ว

บทสรุป

OpenAPI ได้มีการพัฒนาอย่างมีนัยสำคัญ:

OpenAPI 3.0: พื้นฐานที่มี servers, request bodies, callbacks

OpenAPI 3.1: ความเข้ากันได้กับ JSON Schema, ออบเจกต์ webhooks, polymorphism ที่ดีขึ้น

OpenAPI 3.2: เมธอด QUERY, ตัวอย่างที่ปรับปรุง, ความปลอดภัยที่ปรับปรุงดีขึ้น

Modern PetstoreAPI ใช้ OpenAPI 3.2 เพื่อแสดงคุณสมบัติทั้งหมดพร้อมตัวอย่างที่พร้อมใช้งานจริง เป็นการใช้งานอ้างอิงสำหรับการออกแบบ API ที่ทันสมัย

ใช้ Apidog เพื่อทำงานกับ OpenAPI ทุกเวอร์ชัน, ตรวจสอบความถูกต้องของ specs และทดสอบการใช้งาน

คำถามที่พบบ่อย (FAQ)

ฉันควรอัปเกรดเป็น OpenAPI 3.1 หรือ 3.2 หรือไม่?

ถ้าเครื่องมือของคุณรองรับ ก็ควรทำ ความเข้ากันได้ของ JSON Schema ใน OpenAPI 3.1 มีประโยชน์ OpenAPI 3.2 เพิ่มรูปแบบที่ทันสมัย เช่น เมธอด QUERY

OpenAPI 3.0 spec ของฉันจะใช้งานได้กับเครื่องมือ 3.1 หรือไม่?

ส่วนใหญ่จะใช้ได้ แต่ nullable และ exclusiveMinimum/exclusiveMaximum จำเป็นต้องมีการอัปเดต

Code generators รองรับ OpenAPI 3.2 หรือไม่?

การรองรับกำลังเพิ่มขึ้น ตรวจสอบเอกสารประกอบของ generator ของคุณ หลายตัวรองรับ 3.1 แต่มีน้อยตัวที่รองรับ 3.2

ฉันสามารถใช้คุณสมบัติของ OpenAPI 3.2 ในเวอร์ชัน 3.1 ได้หรือไม่?

ไม่ได้ ใช้เวอร์ชันที่ตรงกับคุณสมบัติที่คุณต้องการ หากคุณต้องการเมธอด QUERY ให้ใช้ 3.2

ฉันจะตรวจสอบความถูกต้องของ OpenAPI spec ได้อย่างไร?

ใช้ Apidog เพื่อนำเข้าและตรวจสอบความถูกต้องของ spec ของคุณ มันจะตรวจสอบความถูกต้องของ schema และความสมบูรณ์ของการอ้างอิง

ฉันจะดูตัวอย่าง OpenAPI 3.2 ที่สมบูรณ์ได้ที่ไหน?

Modern PetstoreAPI มี OpenAPI 3.2 specification ที่สมบูรณ์และพร้อมใช้งานจริง

Webhooks และ Callbacks แตกต่างกันอย่างไร?

Webhooks คือ HTTP requests จากเซิร์ฟเวอร์ไปยังไคลเอ็นต์ Callbacks ถูกกำหนดใน OpenAPI 3.0 เป็นส่วนหนึ่งของการดำเนินการ OpenAPI 3.1+ มีออบเจกต์ webhooks โดยเฉพาะ

ฉันควรใช้ JSON หรือ YAML สำหรับ OpenAPI specs ดี?

ทั้งสองใช้งานได้ YAML อ่านง่ายกว่าสำหรับมนุษย์ JSON ง่ายกว่าสำหรับเครื่องมือ Modern PetstoreAPI มีทั้งสองรูปแบบ