Những Thay Đổi OpenAPI 3.2 So Với 3.1 và 3.0?

TÓM TẮT

OpenAPI 3.1 đã bổ sung khả năng tương thích JSON Schema đầy đủ, webhooks và các cải tiến về bộ phân biệt (discriminator). OpenAPI 3.2 đã bổ sung hỗ trợ phương thức QUERY, các ví dụ được cải thiện và các định nghĩa bảo mật tốt hơn. PetstoreAPI hiện đại sử dụng OpenAPI 3.2 để trình bày tất cả các tính năng mới nhất với các ví dụ sẵn sàng cho môi trường sản xuất.

Giới thiệu

Bạn đang viết một đặc tả OpenAPI. Bạn thấy các tham chiếu đến OpenAPI 3.0, 3.1 và 3.2. Sự khác biệt là gì? Bạn có nên nâng cấp không? Các công cụ của bạn có hỗ trợ phiên bản mới không?

OpenAPI đã phát triển đáng kể từ 3.0 đến 3.2. Mỗi phiên bản bổ sung các tính năng giúp đặc tả API mạnh mẽ và chính xác hơn. Nhưng không phải tất cả các công cụ đều hỗ trợ các phiên bản mới nhất, tạo ra thách thức về khả năng tương thích.

Swagger Petstore cũ sử dụng OpenAPI 2.0 (đặc tả Swagger). PetstoreAPI hiện đại sử dụng OpenAPI 3.2, thể hiện mọi tính năng mới với các ví dụ sẵn sàng cho môi trường sản xuất.

Trong hướng dẫn này, bạn sẽ tìm hiểu những gì đã thay đổi trong mỗi phiên bản OpenAPI, cách chọn phiên bản phù hợp và cách PetstoreAPI hiện đại trình bày các tính năng của OpenAPI 3.2.

Nền tảng OpenAPI 3.0

OpenAPI 3.0 (phát hành tháng 7 năm 2017) là một bản nâng cấp lớn từ Swagger 2.0.

Các tính năng chính

1. Nhiều máy chủ (Multiple servers)

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

Swagger 2.0 chỉ hỗ trợ một máy chủ.

2. Đối tượng thân yêu cầu (Request body object)

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

Rõ ràng hơn tham số body của Swagger 2.0.

3. Thành phần (Components) để tái sử dụng

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

Tổ chức tốt hơn definitions của Swagger 2.0.

4. Gọi lại (Callbacks)

Định nghĩa các lệnh gọi lại không đồng bộ (webhooks):

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

5. Liên kết (Links)

Định nghĩa mối quan hệ giữa các hoạt động:

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

Hạn chế

1. Không tương thích JSON Schema

OpenAPI 3.0 sử dụng một tập con của JSON Schema Draft 5, không phải JSON Schema đầy đủ. Điều này gây ra các vấn đề xác thực.

2. Không có đối tượng webhooks

Webhooks được định nghĩa là callbacks, điều này gây nhầm lẫn.

3. Bộ phân biệt (discriminator) hạn chế

Hỗ trợ đa hình cơ bản.

4. Không có kiểu null

Bạn không thể chỉ định trực tiếp type: null.

Những thay đổi lớn trong OpenAPI 3.1

OpenAPI 3.1 (phát hành tháng 2 năm 2021) tập trung vào việc căn chỉnh JSON Schema.

1. Tương thích JSON Schema 2020-12 đầy đủ

Thay đổi lớn nhất: Lược đồ OpenAPI 3.1 là JSON Schema 2020-12 hợp lệ.

Trước đây (OpenAPI 3.0):

type: string
nullable: true  # Đặc tả OpenAPI

Sau này (OpenAPI 3.1):

type: [string, "null"]  # JSON Schema tiêu chuẩn

Lợi ích:

• Sử dụng bất kỳ trình xác thực JSON Schema nào
• Chia sẻ lược đồ giữa OpenAPI và các công cụ khác
• Truy cập vào các tính năng đầy đủ của JSON Schema

2. Đối tượng Webhooks

Trước đây (OpenAPI 3.0):

# Webhooks được định nghĩa là callbacks (gây nhầm lẫn)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # định nghĩa webhook

Sau này (OpenAPI 3.1):

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

Phân tách rõ ràng hơn giữa các điểm cuối API và webhooks.

3. Cải tiến bộ phân biệt (Discriminator)

Hỗ trợ đa hình tốt hơn:

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

4. Mã định danh giấy phép trong đối tượng Info

info:
  license:
    name: MIT
    identifier: MIT  # Mã định danh SPDX

5. Tham chiếu PathItem $ref

Tham chiếu toàn bộ các mục đường dẫn (path items):

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

Thay đổi gây lỗi

1. Loại bỏ nullable

Sử dụng type: [string, "null"] thay thế.

2. exclusiveMinimum/exclusiveMaximum đã thay đổi

Bây giờ là kiểu boolean, không phải số.

3. example so với examples

Xác thực chặt chẽ hơn.

Các tính năng mới nhất của OpenAPI 3.2

OpenAPI 3.2 (dự kiến phát hành, bản nháp đã có) bổ sung các mẫu API hiện đại.

1. Hỗ trợ phương thức QUERY

Phương thức HTTP QUERY cho các tìm kiếm phức tạp:

paths:
  /pets/search:
    query:  # Phương thức mới
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: Kết quả tìm kiếm

PetstoreAPI hiện đại sử dụng QUERY cho các tìm kiếm thú cưng phức tạp.

2. Các ví dụ được cải thiện

Nhiều ví dụ với siêu dữ liệu:

examples:
  availableCat:
    summary: Mèo có sẵn
    description: Một con mèo có sẵn để nhận nuôi
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: Chó được nhận nuôi
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. Các định nghĩa bảo mật nâng cao

Hỗ trợ OAuth 2.0 tốt hơn:

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: Đọc thông tin thú cưng
            pets:write: Tạo và cập nhật thú cưng
            orders:read: Đọc thông tin đơn hàng

4. Cải thiện ánh xạ bộ phân biệt (Discriminator mapping)

Đa hình linh hoạt hơn:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Có thể trộn lẫn tham chiếu cục bộ và $ref

5. Hỗ trợ bỏ dùng tốt hơn

Bỏ dùng các trường cụ thể:

properties:
  oldField:
    type: string
    deprecated: true
    description: Sử dụng newField thay thế
  newField:
    type: string

Cách PetstoreAPI hiện đại sử dụng OpenAPI 3.2

PetstoreAPI hiện đại trình bày mọi tính năng của OpenAPI 3.2.

1. Đặc tả đầy đủ

Đặc tả OpenAPI 3.2 hoàn chỉnh có sẵn tại:

https://petstoreapi.com/openapi.json

2. Phương thức QUERY cho các tìm kiếm phức tạp

/pets/search:
  query:
    summary: Tìm kiếm thú cưng với tiêu chí phức tạp
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. Webhooks

webhooks:
  petStatusChanged:
    post:
      summary: Trạng thái thú cưng đã thay đổi
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. Lược đồ đa hình

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

5. Các ví dụ toàn diện

Mỗi điểm cuối bao gồm nhiều ví dụ minh họa các kịch bản khác nhau.

6. Phản hồi lỗi RFC 9457

responses:
  '400':
    description: Yêu cầu không hợp lệ
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

Xem đặc tả OpenAPI đầy đủ để biết tất cả các tính năng.

Hướng dẫn di chuyển

Từ 3.0 sang 3.1

1. Thay thế nullable:

# Trước đây
type: string
nullable: true

# Sau này
type: [string, "null"]

2. Cập nhật exclusiveMinimum/exclusiveMaximum:

# Trước đây
minimum: 0
exclusiveMinimum: true

# Sau này
minimum: 0
exclusiveMinimum: 0

3. Di chuyển webhooks:

# Trước đây
paths:
  /subscribe:
    callbacks:
      # webhook

# Sau này
webhooks:
  # webhook

Từ 3.1 sang 3.2

1. Thêm các phương thức QUERY khi thích hợp:

/pets/search:
  query:  # Mới trong 3.2
    # tìm kiếm phức tạp

2. Nâng cao các ví dụ:

examples:
  example1:
    summary: Mô tả
    value: {...}

3. Cập nhật các định nghĩa bảo mật:

Thêm refreshUrl vào các luồng OAuth.

Kiểm thử đặc tả OpenAPI bằng Apidog

Apidog hỗ trợ tất cả các phiên bản OpenAPI.

Nhập đặc tả OpenAPI

1. Mở Apidog
2. Nhấp vào "Import" (Nhập)
3. Chọn "OpenAPI 3.x"
4. Dán URL hoặc tải lên tệp
5. Apidog xác thực và nhập

Xác thực đặc tả

Apidog kiểm tra:

• Tính hợp lệ của lược đồ
• Tính toàn vẹn tham chiếu
• Độ chính xác của ví dụ
• Hoàn thiện định nghĩa bảo mật

Kiểm thử triển khai API

Tạo các trường hợp kiểm thử từ đặc tả:

• Xác thực yêu cầu
• Xác thực phản hồi
• Kiểm tra mã trạng thái
• Tuân thủ lược đồ

So sánh phiên bản

Nhập nhiều phiên bản và so sánh:

• Thay đổi gây lỗi
• Các điểm cuối mới
• Thay đổi lược đồ
• Các trường bị bỏ dùng

Kết luận

OpenAPI đã phát triển đáng kể:

OpenAPI 3.0: Nền tảng với máy chủ, thân yêu cầu, callbacks

OpenAPI 3.1: Tương thích JSON Schema, đối tượng webhooks, đa hình tốt hơn

OpenAPI 3.2: Phương thức QUERY, các ví dụ nâng cao, bảo mật được cải thiện

PetstoreAPI hiện đại sử dụng OpenAPI 3.2 để trình bày tất cả các tính năng với các ví dụ sẵn sàng cho môi trường sản xuất. Đây là triển khai tham chiếu cho thiết kế API hiện đại.

Sử dụng Apidog để làm việc với bất kỳ phiên bản OpenAPI nào, xác thực đặc tả và kiểm thử triển khai.

Câu hỏi thường gặp

Tôi có nên nâng cấp lên OpenAPI 3.1 hoặc 3.2 không?

Nếu các công cụ của bạn hỗ trợ, thì có. Khả năng tương thích JSON Schema của OpenAPI 3.1 rất có giá trị. OpenAPI 3.2 bổ sung các mẫu hiện đại như phương thức QUERY.

Đặc tả OpenAPI 3.0 của tôi có hoạt động với các công cụ 3.1 không?

Hầu hết là có, nhưng nullable và exclusiveMinimum/exclusiveMaximum cần được cập nhật.

Các trình tạo mã có hỗ trợ OpenAPI 3.2 không?

Sự hỗ trợ đang tăng lên. Kiểm tra tài liệu của trình tạo của bạn. Nhiều trình hỗ trợ 3.1, ít hơn hỗ trợ 3.2.

Tôi có thể sử dụng các tính năng của OpenAPI 3.2 trong 3.1 không?

Không. Sử dụng phiên bản phù hợp với các tính năng của bạn. Nếu bạn cần phương thức QUERY, hãy sử dụng 3.2.

Làm cách nào để xác thực đặc tả OpenAPI của tôi?

Sử dụng Apidog để nhập và xác thực đặc tả của bạn. Nó kiểm tra tính hợp lệ của lược đồ và tính toàn vẹn tham chiếu.

Tôi có thể xem ví dụ OpenAPI 3.2 hoàn chỉnh ở đâu?

PetstoreAPI hiện đại cung cấp một đặc tả OpenAPI 3.2 hoàn chỉnh, sẵn sàng cho môi trường sản xuất.

Sự khác biệt giữa webhooks và callbacks là gì?

Webhooks là các yêu cầu HTTP từ máy chủ đến máy khách. Callbacks được định nghĩa trong OpenAPI 3.0 như một phần của các hoạt động. OpenAPI 3.1+ có một đối tượng webhooks chuyên dụng.

Tôi nên sử dụng JSON hay YAML cho đặc tả OpenAPI?

Cả hai đều hoạt động. YAML dễ đọc hơn đối với con người. JSON dễ dàng hơn cho các công cụ. PetstoreAPI hiện đại cung cấp cả hai định dạng.