Thiết kế hợp đồng OpenAPI từ user story bằng AI
Playbook chuyển user story thành bản nháp OpenAPI để review: làm rõ giả định, soạn YAML có kiểm soát, kiểm tra cú pháp và nghiệp vụ trước khi dùng contract cho tài liệu, SDK hoặc server stub.
Một user story như “người dùng tạo đơn hàng và xem lại đơn của mình” có thể đủ để product team thảo luận. Nhưng với backend, mobile và QA, nó vẫn để ngỏ những điểm quyết định: endpoint nào, field nào bắt buộc, lỗi phản hồi ra sao, định danh nằm ở đâu và ai được đọc dữ liệu.
Nếu đưa nguyên câu đó cho AI với yêu cầu “viết API”, kết quả thường là một file YAML có vẻ hoàn chỉnh nhưng chứa nhiều quyết định chưa ai phê duyệt.
Cách làm an toàn hơn là dùng AI để soạn bản nháp hợp đồng OpenAPI, rồi để consumer, provider và QA cùng review.
OpenAPI Specification (OAS) là chuẩn mô tả API HTTP độc lập với ngôn ngữ lập trình. Một OpenAPI Description có thể được công cụ dùng để tạo tài liệu, client, server stub và cho các mục đích khác. Vì vậy, contract nên được chốt sớm thay vì chỉ xuất hiện sau khi controller đã được viết.
Quy trình ba lượt: hỏi, soạn, phản biện
Thay vì yêu cầu AI thiết kế toàn bộ API trong một lần, hãy chia nhỏ công việc:
Làm rõ: Trích xuất câu hỏi, rủi ro và giả định từ user story.
Soạn thảo: Chuyển các quyết định đã chốt thành OpenAPI YAML.
Phản biện: Review contract từ góc nhìn consumer, provider và QA.
Theo đặc tả OpenAPI, tài liệu OpenAPI là một JSON object và có thể biểu diễn bằng JSON hoặc YAML. Tên field phân biệt chữ hoa/chữ thường. Root object có các field bắt buộc như openapi và info; đồng thời phải có ít nhất một trong components, paths hoặc webhooks.
AI có thể chuyển quyết định thành YAML nhanh, nhưng không thể tự chịu trách nhiệm cho ý nghĩa nghiệp vụ của xác thực, quyền truy cập hay thao tác xóa.
Dùng prompt đầu tiên để buộc AI chỉ ra phần chưa biết:
text
Bạn là API designer làm việc theo OpenAPI Specification.
Đọc user story dưới đây. Chưa tạo OpenAPI YAML.
Hãy trả về:
actors và quyền cần xác định;
tài nguyên chính;
thao tác HTTP có thể cần;
request/response cần làm rõ;
lỗi nghiệp vụ và lỗi HTTP chưa được quyết định;
mọi giả định của bạn.
User story:
<userstory>
Bối cảnh hệ thống:
<systemcontext>
Đầu ra cần tìm ở bước này không phải một spec dài, mà là danh sách câu hỏi cho buổi refinement.
Ví dụ, từ cụm “xem đơn của mình”, team cần chốt:
API lấy một đơn hay danh sách đơn?
Người dùng có thể đọc đơn không thuộc về họ không?
Đơn có những trạng thái nào?
Khi không tìm thấy đơn hoặc không có quyền đọc, API cần phản hồi theo quy ước nào?
Walkthrough: từ user story đến YAML để review
Giả sử backlog có user story:
> Là người mua, tôi muốn tạo đơn hàng để mua các sản phẩm đã chọn.
Sau refinement, chỉ đưa cho AI những quyết định đã được chốt. Không cần đưa toàn bộ codebase vào cửa sổ chat; chỉ cung cấp ngữ cảnh tối thiểu và được phép chia sẻ.
text
Tạo bản nháp OpenAPI YAML theo OpenAPI 3.2.0.
Quyết định đã chốt:
Có endpoint tạo đơn hàng.
Request chứa danh sách mặt hàng.
Mỗi mặt hàng có mã sản phẩm và số lượng.
Không tự thêm endpoint, field, trạng thái, mã phản hồi
hoặc cơ chế xác thực ngoài dữ liệu này.
Nếu chi tiết chưa có, ghi rõ "Cần xác nhận" trong description.
Yêu cầu:
Có openapi, info, paths và components.
Đặt schema có tên rõ nghĩa trong components.
Khai báo requestBody.
Mỗi response phải có description.
Trả về YAML thuần, không giải thích ngoài YAML.
Bản nháp dưới đây cố ý chưa chốt version nghiệp vụ, mã phản hồi thành công và schema response. Những điểm đó được ghi rõ để đưa vào review, thay vì để AI tự quyết.
yaml
openapi: 3.2.0
info:
title: Order API
version: "Cần xác nhận version API"
paths:
/orders:
post:
summary: Create an order
description: >
Tạo đơn hàng từ danh sách mặt hàng.
Cần xác nhận quy tắc tạo đơn và quyền thực hiện thao tác này.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
default:
description: >
Cần xác nhận mã phản hồi, content type và schema body
cho cả trường hợp thành công lẫn lỗi.
components:
schemas:
CreateOrderRequest:
type: object
description: >
Yêu cầu tạo đơn hàng. Cần xác nhận danh sách items có được
phép rỗng hay không.
required:
items
properties:
items:
type: array
description: >
Danh sách mặt hàng. required chỉ yêu cầu field này xuất hiện;
không tự cấm mảng rỗng.
items:
$ref: '#/components/schemas/OrderItem'
OrderItem:
type: object
description: Một mặt hàng trong yêu cầu tạo đơn.
required:
productId
quantity
properties:
productId:
type: string
description: >
Mã sản phẩm. Cần xác nhận đây là mã nội bộ, SKU
hay một định danh khác.
quantity:
type: integer
description: >
Số lượng đặt mua. type integer không tự bảo đảm giá trị dương;
cần xác nhận giới hạn hợp lệ.
Đây chưa phải API hoàn chỉnh để đưa vào production. Nó là artefact đủ rõ để mở pull request và comment trực tiếp vào contract:
productId là mã nội bộ, SKU hay định danh khác?
items có được rỗng không? Nếu không, cần bổ sung ràng buộc phù hợp.
quantity có phải số nguyên dương không? Có giới hạn trên không?
API phản hồi mã nào khi tạo đơn thành công?
Response thành công cần trả về những field nào?
Error body có cấu trúc chung nào để consumer xử lý nhất quán?
Kiểm tra trước khi sinh mã
Theo OpenAPI, OpenAPI Description có thể là đầu vào cho công cụ sinh client, server và tài liệu. OpenAPI Generator là dự án mã nguồn mở được cấp phép Apache 2.0; README của dự án cho biết công cụ có thể sinh API client, server stub hoặc documentation từ spec.
README cũng cảnh báo: nếu spec, template, option hoặc biến môi trường đến từ nguồn không tin cậy, cần review chúng trước khi chạy sinh mã để tránh rủi ro bảo mật, chẳng hạn code injection.
Với workflow có AI, hãy xem YAML do assistant tạo như input từ một contributor mới: cần review trước khi đưa vào pipeline.
Tư liệu tham chiếu không cung cấp câu lệnh cài đặt hoặc chạy OpenAPI Generator. Vì vậy, không nên đưa command do AI tự đề xuất vào CI khi chưa đối chiếu tài liệu chính thức và cấu hình của repository.
Tách validate kỹ thuật khỏi review nghiệp vụ
Trước khi merge, nên có một bước tự động để validate hoặc lint file OpenAPI theo phiên bản OAS mà team sử dụng. Bước này phù hợp để phát hiện lỗi kỹ thuật như YAML không hợp lệ, field viết sai, $ref không trỏ được hoặc cấu trúc spec không đạt yêu cầu của công cụ.
Tuy nhiên, validate không xác nhận API có đúng nghiệp vụ. Một contract vẫn có thể hợp lệ về cú pháp dù sai quyền truy cập, thiếu tình huống lỗi hoặc chọn semantics không phù hợp.
Vì vậy, review nên đi qua ba lớp:
Cú pháp và cấu trúc: YAML hợp lệ, root field cần thiết có mặt, paths và $ref nhất quán.
Tương thích consumer: Request, response, content type và schema đủ rõ để client tích hợp.
Nghiệp vụ: Quyền truy cập, mã phản hồi, điều kiện biên và ý nghĩa lỗi đã được owner xác nhận.
Dùng prompt review để AI phản biện thay vì tiếp tục viết thêm spec:
text
Hãy review OpenAPI YAML dưới đây như một consumer API và một QA engineer.
Chỉ ra:
field bắt buộc nhưng chưa được mô tả rõ;
response thiếu schema hoặc chưa chốt mã phản hồi;
các trường hợp lỗi cần chốt;
schema có thể gây khó cho client generation;
giả định nghiệp vụ không có trong user story.
Không tự sửa YAML. Với mỗi vấn đề, nêu một câu hỏi review ngắn.
User story:
<userstory>
OpenAPI YAML:
<openapiyaml>
Mẫu tiêu chí chấp nhận cho PR contract
Để consumer, provider và QA review nhất quán, hãy thêm các tiêu chí sau vào pull request:
[ ] User story và phạm vi endpoint đã được nêu rõ.
[ ] Mọi field bắt buộc đều có ý nghĩa và kiểu dữ liệu rõ ràng.
[ ] Các ràng buộc quan trọng, như mảng rỗng hoặc số lượng dương, đã được chốt thay vì ngầm suy diễn từ kiểu dữ liệu.
[ ] Mã phản hồi, content type và schema body đã được thống nhất cho các luồng cần hỗ trợ.
[ ] Lỗi nghiệp vụ và lỗi HTTP có semantics rõ ràng cho consumer.
[ ] Quyền truy cập và phạm vi dữ liệu đã được xác nhận.
[ ] Consumer xác nhận contract đủ để tích hợp.
[ ] Provider xác nhận contract có thể triển khai.
[ ] QA xác nhận các trường hợp kiểm thử chính và điều kiện biên.
[ ] File đã qua validate hoặc lint tự động.
Những điểm AI không thể tự giải quyết
AI có thể lấp chỗ trống bằng endpoint, field hoặc error code nghe hợp lý. Nhưng điều đó không bảo đảm phù hợp domain hay tương thích với hệ thống hiện có.
Một số lưu ý khi làm việc với OpenAPI:
OpenAPI được version theo major, minor và patch. Feature set được xác định bởi phần major/minor; tooling hỗ trợ một phiên bản minor nên tương thích với các bản patch thuộc phiên bản đó.
Không nên dựa vào hành vi undefined, vì kết quả không được bảo đảm giữa các công cụ hoặc phiên bản tương lai.
Field description hỗ trợ CommonMark. Các Markdown extension có thể phụ thuộc cách triển khai, nên giữ mô tả đơn giản khi spec được render bởi nhiều công cụ.
Không đưa secret, access token, dữ liệu khách hàng hoặc nội dung nội bộ nhạy cảm vào prompt.
Review cả YAML lẫn mã được sinh. Code generation không biến contract sai thành contract đúng.
Checklist trước khi merge
[ ] User story đã được chuyển thành các quyết định cụ thể.
[ ] File có openapi và info.
[ ] File có ít nhất một trong paths, components hoặc webhooks.
[ ] Các chi tiết chưa chốt được đánh dấu rõ để review.
[ ] required và kiểu dữ liệu không bị hiểu nhầm là ràng buộc nghiệp vụ đầy đủ.
[ ] Contract đã qua validate hoặc lint tự động.
[ ] Consumer, provider và QA đã review pull request.
[ ] Input cho code generator đã được kiểm tra, đặc biệt khi đến từ AI hoặc nguồn ngoài.
Điểm mạnh của AI không phải là tự quyết API thay team. Nó rút ngắn đoạn đường từ user story mơ hồ đến một contract đủ cụ thể để bị phản biện, sửa và dùng chung.