Cách viết tài liệu cho Kafka API: Topics, Schemas và Contracts

Một Kafka topic không có endpoint để đọc, nên hợp đồng của nó phải được ghi chép lại. Dưới đây là những gì cần tài liệu hóa cho mỗi topic, cách diễn đạt bằng AsyncAPI, và cách để coding agent của bạn luôn giữ thông tin này đồng bộ.

Ashley Innocent

Ashley Innocent

16 tháng 11 2026

Cách viết tài liệu cho Kafka API: Topics, Schemas và Contracts

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Để tài liệu hóa các Kafka API, hãy viết một hợp đồng (contract) cho mỗi topic. Hợp đồng đó cần nêu tên topic, khóa sự kiện (event key), schema của payload, các headers, cam kết về thứ tự và đảm bảo gửi tin (delivery guarantees), các consumer group, thời gian lưu trữ (retention) và bên sở hữu. Sau đó, lưu hợp đồng này cùng với tài liệu HTTP API của bạn, để producer và consumer cùng đọc một nguồn thông tin duy nhất thay vì phải dịch ngược nội dung message từ cluster đang chạy.

Bài hướng dẫn này bao gồm từng phần của hợp đồng đó, cách viết bằng AsyncAPI, cách tiến hóa schema một cách an toàn, và cách để agent lập trình của bạn làm việc này bằng Apidog CLI.

Nếu bạn mới làm quen với thiết kế hướng sự kiện (event-driven), hãy bắt đầu với bài cách xây dựng event-driven API và hướng dẫn về webhook và kiến trúc hướng sự kiện.

Kafka API là gì?

Kafka API là tập hợp các topic, định dạng message và quy tắc gửi tin mà các dịch vụ dùng để trao đổi sự kiện qua một cluster Apache Kafka. Khác với REST API, không ai gọi một endpoint rồi chờ phản hồi. Producer ghi record vào topic, consumer đọc record theo lịch riêng của mình, và hợp đồng nằm ở cấu trúc cũng như ý nghĩa của những record đó.

Tài liệu Kafka viết rất rõ ràng: "một sự kiện có key, value, timestamp và các metadata headers tùy chọn". Bản thân Kafka không kiểm tra nội dung bên trong value. Producer có thể ghi JSON hôm nay và một cấu trúc JSON khác vào ngày mai, và broker vẫn chấp nhận cả hai. Đó là lý do Kafka API cần hợp đồng bằng văn bản nhiều hơn so với HTTP API: không có gì ở tầng vận chuyển (transport) ngăn được một thay đổi gây lỗi (breaking change).

Các topic không được tài liệu hóa thường lỗi theo những cách dễ đoán: một consumer đoán kiểu dữ liệu của một trường từ một mẫu message rồi bị lỗi khi gặp null, hoặc một dịch vụ mới không biết rằng mỗi message được nhận ít nhất một lần và tính phí trùng lặp khi retry.

Cần tài liệu hóa những gì cho mỗi Kafka topic

Mỗi topic cần cùng một nhóm thông tin cốt lõi. Hãy dùng bảng này như checklist của bạn:

Trường hợp đồng Nội dung cần ghi Ví dụ
Tên topic Tên đầy đủ và quy ước đặt tên orders.order-placed.v1
Mục đích Một câu mô tả ý nghĩa của sự kiện "Một đơn hàng đã qua thanh toán và sẵn sàng giao"
Khóa sự kiện (Event key) Trường nào là khóa, và tại sao customerId, để các đơn hàng của một khách hàng giữ đúng thứ tự
Schema payload Mọi trường, kiểu dữ liệu, cờ bắt buộc và định dạng JSON Schema, Avro hoặc Protobuf
Headers Tên, kiểu và ý nghĩa của từng header traceparent, schema-version
Partition và thứ tự Số lượng partition và cam kết về thứ tự 12 partition, có thứ tự theo customerId
Ngữ nghĩa gửi tin (Delivery semantics) At least once, producer idempotent, transactions At least once; consumer phải khử trùng lặp theo orderId
Consumer group Các group đã biết và vai trò của từng group billing-service, email-notifier
Retention Record được giữ đọc được trong bao lâu 7 ngày
Sở hữu Team sở hữu, liên hệ và chính sách phiên bản Team Checkout, #checkout-events

Hai dòng về thứ tự và gửi tin là quan trọng nhất: người đọc không thể suy ra chúng từ một message mẫu.

Sơ đồ hợp đồng Kafka topic: producer ghi các sự kiện có khóa vào một topic phân partition được hai consumer group đọc, với các trường hợp đồng ở bên cạnh

Tài liệu hóa Kafka API trong 6 bước

  1. Liệt kê mọi topic và bên sở hữu. Lấy danh sách topic từ cluster và ghi rõ ai là producer của từng topic.
  2. Xác định khóa. Ghi rõ trường nào là khóa và điều đó có ý nghĩa gì với thứ tự.
  3. Viết schema payload. Mô tả từng trường bằng JSON Schema, Avro hoặc Protobuf.
  4. Mô tả headers và metadata. Bao gồm header tracing, phiên bản schema và content type.
  5. Nêu rõ các cam kết. Tài liệu hóa ngữ nghĩa gửi tin, phạm vi thứ tự, retention và các consumer group.
  6. Xuất bản ở nơi mọi người tìm thấy. Đặt hợp đồng cạnh tài liệu HTTP API và quản lý phiên bản như code.

Bước 1 và 2: topic và khóa

Mẫu đặt tên như <domain>.<event>.<version> cho người đọc biết topic thuộc ai và họ đang đọc phiên bản nào. Sau đó hãy tài liệu hóa khóa, vì khóa quyết định partition. Tài liệu Kafka khẳng định rằng "các sự kiện có cùng event key (ví dụ: ID khách hàng hoặc ID xe) sẽ được ghi vào cùng một partition", và consumer đọc các sự kiện của một partition "đúng theo thứ tự mà chúng được ghi".

Vì vậy hợp đồng của bạn nên ghi "có thứ tự theo customerId", chứ không chỉ "có thứ tự". Kafka chỉ đảm bảo thứ tự trong một partition, không bao giờ trên toàn topic.

Bước 3: schema payload

Payload là phần mà consumer viết code dựa trên, nên hãy mô tả nó theo từng trường. Đây là một JSON Schema cho sự kiện order-placed:

{
  "type": "object",
  "required": ["orderId", "customerId", "totalCents", "currency", "placedAt"],
  "properties": {
    "orderId": { "type": "string", "description": "Unique order ID; use it to deduplicate" },
    "customerId": { "type": "string", "description": "Also the record key" },
    "totalCents": { "type": "integer", "minimum": 0 },
    "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
    "placedAt": { "type": "string", "format": "date-time" },
    "couponCode": { "type": ["string", "null"] }
  }
}

Phần mô tả "use it to deduplicate" cho consumer biết phải làm gì với trường đó, chứ không chỉ kiểu dữ liệu. Mới quen với định dạng này? Đọc bài JSON Schema là gì.

Bước 4 và 5: headers và cam kết

Liệt kê từng header (trace context, phiên bản schema, content type) và nêu rõ consumer có thể tin tưởng vào nó hay không. Sau đó ghi lại cam kết gửi tin bằng thuật ngữ của chính Kafka. Tài liệu thiết kế Kafka nêu rõ "Kafka mặc định đảm bảo gửi ít nhất một lần (at-least-once)", nghĩa là message "không bao giờ bị mất nhưng có thể được gửi lại". Nếu producer của bạn dùng chế độ idempotent hoặc transactions, hãy ghi rõ. Nếu không, hãy bảo consumer khử trùng lặp, và chỉ định trường để khử trùng lặp.

Cũng cần tài liệu hóa các consumer group. Trong mỗi group đăng ký, một partition "chỉ được một consumer tiêu thụ" tại một thời điểm. Điều đó cho người đọc biết một group có thể mở rộng đến đâu: một consumer hoạt động cho mỗi partition.

Viết hợp đồng bằng AsyncAPI

Công cụ cần một định dạng máy đọc được, và với Kafka thường là AsyncAPI — một đặc tả "dùng để mô tả các API hướng message ở định dạng máy đọc được". Nó đóng vai trò tương tự OpenAPI đối với REST.

Một tài liệu AsyncAPI 3.0 có các phần info, servers, channels, operations và components. Một channel ánh xạ tới một topic qua thuộc tính address, và mỗi operation có một action là send hoặc receive:

asyncapi: 3.0.0
info:
  title: Orders events
  version: 1.0.0
channels:
  orderPlaced:
    address: orders.order-placed.v1
    messages:
      orderPlaced:
        $ref: '#/components/messages/orderPlaced'
operations:
  publishOrderPlaced:
    action: send
    channel:
      $ref: '#/channels/orderPlaced'
components:
  messages:
    orderPlaced:
      payload:
        $ref: './schemas/order-placed.json'

AsyncAPI cũng có các Kafka binding ở cấp server, channel, operation và message. Đây là nơi chứa các chi tiết đặc thù của Kafka mà các trường chung không thể diễn đạt được. Hãy giữ đặc tả này trong repo của producer, để pull request thay đổi một sự kiện cũng thay đổi hợp đồng của nó.

Tiến hóa schema Kafka: tài liệu hóa quy tắc tương thích

Schema của bạn sẽ thay đổi theo thời gian. Hợp đồng cần nói rõ thay đổi nào là an toàn. Nếu bạn dùng schema registry, hãy tài liệu hóa chế độ tương thích (compatibility mode) của nó. Tài liệu tiến hóa schema của Confluent liệt kê các chế độ này, và lưu ý rằng "kiểu tương thích mặc định của Confluent Schema Registry là BACKWARD":

Chế độ Ai đọc được gì
BACKWARD Consumer dùng schema mới có thể đọc dữ liệu được ghi với schema trước đó
BACKWARD_TRANSITIVE Consumer dùng schema mới có thể đọc dữ liệu từ tất cả các schema cũ hơn
FORWARD Consumer dùng schema trước đó có thể đọc dữ liệu được ghi với schema mới
FORWARD_TRANSITIVE Consumer dùng bất kỳ schema cũ hơn nào cũng có thể đọc dữ liệu được ghi với schema mới
FULL Tương thích cả hai chiều với schema trước đó
FULL_TRANSITIVE Tương thích cả hai chiều với tất cả các schema cũ hơn
NONE Tắt kiểm tra tương thích

Trong thực tế, với chế độ BACKWARD bạn có thể thêm trường tùy chọn và xóa các trường có giá trị mặc định. Đổi tên một trường bắt buộc hoặc thay đổi kiểu của nó sẽ làm hỏng consumer. Khi cần thay đổi gây lỗi, hãy xuất bản một phiên bản topic mới (orders.order-placed.v2), tài liệu hóa cả hai phiên bản, và đặt ngày nghỉ hoạt động cho phiên bản cũ.

Để agent lập trình tài liệu hóa Kafka API bằng Apidog CLI

Hợp đồng viết tay sẽ lạc hậu ngay khi có người thay đổi producer. Agent lập trình của bạn có thể đọc code producer, viết các schema và giữ tài liệu luôn đồng bộ trong khi bạn chỉ cần rà soát. Apidog CLI cung cấp cho Claude Code, Codex, Cursor hoặc bất kỳ agent terminal nào các lệnh cần thiết để làm điều đó trong một dự án Apidog.

Cài CLI, đăng nhập và thêm skill Apidog để agent của bạn biết các lệnh:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Bạn cũng có thể giao việc cài đặt cho agent: bảo nó đọc hướng dẫn cài đặt Apidog CLI và tự thiết lập.

Sau đó đưa cho agent một prompt:

Read the Kafka producers in ./services/orders. For every topic they write to,
create an Apidog data schema in project <projectId> for the message payload,
then create one Markdown doc per topic with the key, headers, ordering,
delivery guarantee, consumer groups, retention and owner. Validate every
payload before you write it.

Agent sẽ kiểm tra cấu trúc payload, xác thực file, rồi ghi schema và trang hợp đồng:

apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file order-placed.schema.json
apidog schema create --project <projectId> --file order-placed.schema.json
apidog cli-schema get doc-create
apidog doc create --project <projectId> --file order-placed.doc.json
apidog schema list --project <projectId>

apidog schema create lưu payload thành một data schema có thể tái sử dụng. Các endpoint HTTP của bạn có thể tham chiếu cùng một model, nên một Order được định nghĩa một lần bao trùm cả REST response lẫn Kafka event. apidog doc create ghi một tài liệu Markdown vào cây dự án, nơi lưu hợp đồng topic từ bảng phía trên. Khi producer thay đổi, chỉ cần chạy lại prompt và agent dùng apidog schema update. Để xem hướng dẫn chi tiết hơn về công việc tài liệu hóa do agent thực hiện, hãy xem bài cách tài liệu hóa API từ CLI và Apidog CLI trong Claude Code.

Sơ đồ quy trình: agent lập trình đọc code producer và chạy apidog schema create và apidog doc create vào một dự án Apidog

Có một bước vẫn phải thực hiện trong ứng dụng. Custom Protocol API của Apidog tài liệu hóa các endpoint Kafka cạnh các endpoint HTTP: chọn New Other Protocol APIs, rồi Other Custom Protocol API, chọn Kafka làm protocol, và điền URI (là topic), tên, trạng thái, người duy trì, thẻ và mô tả. Các mục này dùng chung cây thư mục, tìm kiếm và Quick Share với tài liệu HTTP của bạn. CLI hiện chưa có lệnh cho endpoint custom protocol, nên đây là phần duy nhất bạn phải tạo thủ công.

Apidog Free hỗ trợ tối đa 4 người dùng, nên một nhóm nhỏ có thể giữ tài liệu REST và Kafka trong cùng một dự án mà không tốn chi phí.

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

Có OpenAPI dành cho Kafka không?

AsyncAPI đảm nhận vai trò đó. Nó mô tả server, channel (topic), operation và payload của message bằng YAML hoặc JSON, kèm các binding đặc thù cho Kafka.

Tôi có cần schema registry để tài liệu hóa Kafka API không?

Không, nhưng nó rất hữu ích. Tài liệu nêu các quy tắc; schema registry thực thi chúng ngay khi ghi dữ liệu. Nếu bạn chạy một schema registry, hãy tài liệu hóa chế độ tương thích của nó.

Tài liệu hóa một Kafka topic khác gì với một REST endpoint?

Tài liệu REST mô tả một request và một response. Tài liệu Kafka mô tả một message mà nhiều consumer đọc sau đó, nên nó cũng cần khóa, phạm vi thứ tự, cam kết gửi tin, retention và các consumer group. Không mục nào trong số đó xuất hiện trong một tài liệu REST thông thường.

Apidog có thể kiểm thử Kafka message không?

Apidog tài liệu hóa các endpoint Kafka thông qua Custom Protocol API, nhưng nó không gửi hay tiêu thụ Kafka message. Hãy dùng Apidog để lưu hợp đồng và các schema payload, còn việc kiểm thử code producer và consumer thì dùng thư viện Kafka client của bạn.

Bao lâu thì tôi nên cập nhật tài liệu Kafka?

Mỗi khi một producer thay đổi message. Hãy gắn nó với code review: pull request thay đổi sự kiện cũng cập nhật hợp đồng, hoặc để agent của bạn tái tạo hợp đồng bằng Apidog CLI.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API