OpenAPI và hệ Swagger, Stoplight, ReadMe: một file spec cho cả đội tích hợp lẫn LLM

Georges Haidar của Speakeasy rút ra một bài học sau khi đội ông dựng hơn 50 MCP server chạy production từ file OpenAPI: khi phải chọn giữa 200 tool, mô hình bị rối vì context window quá tải. Nhận xét ấy cho thấy cả điểm mạnh lẫn chỗ dễ vấp của chuẩn mô tả API phổ biến nhất hiện nay.

Điểm mạnh là một file spec giờ phục vụ được hai kiểu người đọc. Đội tích hợp bên khách đọc nó qua trang docs, còn agent đọc nó dưới dạng danh sách tool. Chỗ dễ vấp nằm ở việc hai kiểu người đọc ấy cần những thứ khác nhau.

Nếu bạn muốn làm FDE, hãy coi đây là kỹ năng cần có sẵn. Khi khách hỏi hệ thống của bạn nối vào ERP của họ bằng cách nào, hay muốn cho agent gọi API nội bộ, một spec sạch là thứ nên đưa ra đầu tiên.

OpenAPI là chuẩn, Swagger là công cụ

Nhiều developer vẫn dùng lẫn hai cái tên, và lịch sử giải thích lý do. Swagger bắt đầu từ Tony Tam tại Wordnik năm 2009. Tháng 12/2015, SmartBear trao đặc tả cho một nhóm quản trị mở dưới Linux Foundation, và OpenAPI 2.0 giống hệt Swagger 2.0.

Từ đó, OpenAPI là chuẩn do OpenAPI Initiative quản lý. Đặc tả mô tả HTTP API độc lập với ngôn ngữ lập trình, và bản mới nhất trên trang chính thức là 3.2.1. Swagger thì là bộ công cụ của SmartBear xây quanh chuẩn này.

Bộ mã nguồn mở của nó gồm Editor để viết spec trên trình duyệt, UI để xem và gọi thử API, và Codegen để sinh client library, server stub và tài liệu.

Stoplight là nền tảng thiên về design-first, nghĩa là viết spec trước rồi mới code, và nay cũng thuộc SmartBear sau thương vụ mua lại. Redoc là công cụ mã nguồn mở khác, chuyên sinh tài liệu từ spec, hỗ trợ OpenAPI 3.1, 3.0 và Swagger 2.0.

Khi đọc JD mà thấy “Swagger” hay “OpenAPI”, bạn có thể hiểu họ cùng đang hỏi một kỹ năng: mô tả API sao cho máy đọc được.

Một spec, năm bước

Thử hình dung khách là một công ty logistics, cần đội IT của họ tích hợp với dịch vụ tra cứu đơn hàng bạn đang dựng. Backend chưa xong, nhưng hai bên cần thống nhất ngay request và response trông thế nào. Bước đầu tiên là viết spec; bản tối thiểu cho một endpoint có thể trông như sau:

openapi: 3.1.0
info:
  title: Order Status API
  version: 0.1.0
paths:
  /orders/{order_id}:
    get:
      operationId: getOrderStatus
      summary: Lấy trạng thái một đơn hàng
      description: >
        Dùng khi người dùng hỏi một đơn cụ thể đang ở đâu.
        Cần order_id dạng chuỗi; không dùng để liệt kê nhiều đơn.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Trạng thái hiện tại của đơn

Bước thứ hai là chạy Spectral, linter JSON/YAML mã nguồn mở của Stoplight, để áp style guide tự động. Spectral hỗ trợ OpenAPI 2 đến 3.1, cùng Arazzo và AsyncAPI, nên bạn gắn nó vào CI để không ai merge một spec thiếu operationId hay thiếu description.

Bước thứ ba là Prism, cũng của Stoplight, biến file OpenAPI hoặc Postman Collection thành mock server có validation. Đội IT của khách gọi thử ngay hôm nay, gửi sai kiểu dữ liệu là bị báo lỗi, trong khi backend thật vẫn đang được viết. Đây thường là cách nhanh nhất để lộ ra hiểu lầm về schema trước khi nó thành bug lúc go-live.

Bước thứ tư là tài liệu: Swagger UI hoặc Redoc dựng trang docs từ chính file đó, còn Swagger Codegen sinh SDK nếu khách muốn. Không ai phải viết tay một trang wiki rồi quên cập nhật.

Khi người đọc là LLM

Bước thứ năm mới là chỗ dễ sai. ReadMe sinh MCP server thẳng từ OpenAPI spec, kèm tool get-endpoint để xem chi tiết một endpoint và tool execute-request để gọi API thật rồi trả kết quả. Agent của khách đọc spec, chọn endpoint và gọi luôn.

Mặc định, mọi endpoint trong spec đều được mở cho AI assistant, và bạn bật tắt được từng cái. Nếu API của khách có 180 endpoint mà agent chỉ cần 6 cho use case tra cứu đơn, hãy tắt 174 cái còn lại. Cảnh báo của Speakeasy về 200 tool chính là lý do: cách chuyển mỗi operation thành một tool sẽ nhồi đầy context của mô hình.

Vấn đề thứ hai là description. Haidar viết thẳng rằng mô tả trong OpenAPI không được thiết kế cho LLM. “Lấy trạng thái một đơn hàng” đủ cho một developer, nhưng mô hình cần biết dùng trong tình huống nào và không dùng khi nào. Đó là lý do dòng description trong ví dụ trên nói rõ “không dùng để liệt kê nhiều đơn”.

Giới hạn cần biết trước

OpenAPI là chuẩn cho HTTP API. Nếu khách chạy hệ thống event, chuẩn liên quan là AsyncAPI; Spectral lint được, nhưng tính năng MCP của ReadMe nói trên được mô tả là sinh từ OpenAPI spec, nên bạn cần kiểm tra riêng trước khi hứa với khách. Spec cũng chỉ đúng khi được bảo trì: mock của Prism và docs của Redoc sẽ sai y như spec sai.

Cũng đừng nhầm “có MCP server” với “agent dùng tốt”. Tool execute-request gọi API thật, nên phân quyền và phạm vi endpoint được mở là quyết định bạn phải bàn với khách, không nên phó mặc cho thiết lập mặc định.

Ba lỗi hay gặp, và một bài tập để tránh chúng

Lỗi đầu tiên là để nguyên mặc định, mở mọi endpoint cho agent rồi ngạc nhiên khi mô hình chọn sai. Lỗi thứ hai là giữ description viết cho người, kiểu một dòng summary, thay vì nói rõ dùng khi nào và không dùng khi nào.

Lỗi thứ ba là coi spec là tài liệu viết một lần, không lint trong CI, để nó lệch dần khỏi code và kéo theo mock lẫn docs sai.

Bài tập: thêm vào file YAML ở trên một endpoint GET /orders để liệt kê đơn theo khách hàng. Viết description cho cả hai endpoint sao cho một người không biết code vẫn chọn đúng giữa “tra một đơn” và “liệt kê nhiều đơn”, rồi chạy Spectral và Prism. Nếu bạn phải đọc schema mới phân biệt được hai endpoint, mô hình cũng sẽ khó phân biệt.

Học gì trước

Bắt đầu từ chuẩn, không phải từ công cụ. Đọc phần paths, parameters, components/schemas của đặc tả, viết tay spec cho một API bạn quen, rồi chạy Spectral và Prism trên đó. Khi đã thạo, thêm bước thứ năm: tự hỏi mỗi description có đủ để một mô hình chọn đúng hay không.

Trên CV, đừng ghi chung chung “biết Swagger”. Ghi rằng bạn dựng quy trình spec-first có lint trong CI, mock cho đối tác tích hợp, và tuyển chọn endpoint cho agent. Ba ý đó cho nhà tuyển dụng thấy bạn hiểu spec phục vụ cả người lẫn máy.

Spec từng là thứ viết cho xong để đóng ticket. Giờ nó là giao diện mà cả đội IT của khách lẫn agent của họ cùng đọc.