Sinh file đặc tả OpenAPI 3.0 cho một endpoint REST từ vài ô nhập
Công cụ nhận tên API, đường dẫn endpoint, phương thức HTTP, danh sách tham số, kiểu xác thực và một ví dụ thân yêu cầu, rồi dựng ra khối văn bản đặc tả theo chuẩn OpenAPI phiên bản 3.0.3. Kết quả cập nhật ngay khi bạn gõ và có nút sao chép, dùng làm điểm khởi đầu cho tệp đặc tả trong kho mã thay vì gõ tay từ dòng đầu tiên.
Tính năng nổi bật
- Sinh khối đặc tả OpenAPI 3.0.3 đầy đủ khối info, paths và operation cho một endpoint
- Cập nhật kết quả tức thời theo từng ký tự gõ vào, không cần bấm nút tạo
- Chuyển danh sách tham số viết theo từng dòng thành mảng parameters đúng cấu trúc
- Tự đánh dấu bắt buộc cho tham số nằm trên đường dẫn, giữ nguyên tùy chọn cho tham số truy vấn
- Dựng sẵn khối securitySchemes cho hai kiểu xác thực là mã thông báo Bearer và khóa API trên header
- Đưa ví dụ thân yêu cầu vào khối requestBody khi phương thức thuộc nhóm ghi dữ liệu
- Hai định dạng đầu ra là JSON và YAML, cả hai đều hợp lệ và dán thẳng vào Swagger Editor được
- Nút sao chép toàn bộ đặc tả với phản hồi trực quan sau khi chép xong
Viết tay khối đặc tả đầu tiên là việc dễ sai và không ai muốn làm
Cấu trúc của một tệp OpenAPI có nhiều tầng lồng nhau đến mức khó nhớ chính xác. Chỉ để mô tả một endpoint lấy danh sách khách hàng, bạn phải xếp đúng thứ tự khối phiên bản, khối thông tin chung, khối đường dẫn, bên trong đường dẫn là phương thức, bên trong phương thức là tóm tắt, mảng tham số, khối thân yêu cầu và khối phản hồi, mà mỗi khối lại có tên trường riêng dễ nhầm. Sai một cấp thụt đầu dòng hoặc viết nhầm parameters thành parameter là bộ đọc báo lỗi mà không chỉ rõ chỗ nào. Trong thực tế, phần lớn người viết đều đi tìm một tệp cũ của dự án khác rồi chép lại và sửa dần, cách này kéo theo cả những trường thừa không liên quan. Điền vài ô rồi lấy khối văn bản đã đúng cấu trúc nhanh hơn và sạch hơn, còn thời gian dành cho phần thực sự cần suy nghĩ là mô tả lược đồ phản hồi và các mã lỗi.
Lợi ích khi sử dụng
- Có ngay bộ khung đúng chuẩn để bắt đầu, không phải nhớ tên và thứ tự từng trường lồng nhau
- Thấy tức thì tác động của mỗi ô nhập lên đặc tả nên học được cấu trúc trong lúc dùng
- Khối xác thực được dựng sẵn đúng cách, gồm cả phần khai báo chung lẫn phần tham chiếu ở endpoint
- Có một khối văn bản cụ thể để mang ra thảo luận thống nhất giao kèo với người làm giao diện và người kiểm thử
- Không cần cài công cụ dòng lệnh hay đăng nhập vào dịch vụ nào, mọi thứ chạy trong trình duyệt
Năm ô cần điền và thứ tự nên điền
- 1Đặt tên API ở ô đầu tiên, đây là tên hiển thị trên đầu trang tài liệu khi bạn nạp tệp vào một bộ xem đặc tả.
- 2Nhập đường dẫn endpoint bắt đầu bằng dấu gạch chéo, ví dụ gạch chéo api gạch chéo customers, rồi ghi phương thức bằng chữ thường.
- 3Khai báo tham số theo từng dòng với ba phần cách nhau bởi dấu hai chấm là tên, vị trí và kiểu dữ liệu.
- 4Chọn kiểu xác thực bằng cách gõ none, bearer hoặc apiKey vào ô tương ứng, chú ý viết đúng chữ hoa chữ thường ở lựa chọn cuối.
- 5Nếu phương thức là post, put hoặc patch thì dán một ví dụ thân yêu cầu hợp lệ, sau đó bấm sao chép và dán vào tệp đặc tả trong kho mã.
Đặc tả, trang tài liệu và công cụ gọi thử là ba thứ khác nhau
Nhiều người gộp chung ba khái niệm này nên hay chọn nhầm công cụ. Đặc tả là một tệp văn bản mô tả toàn bộ giao kèo của API: có những đường dẫn nào, mỗi đường dẫn nhận tham số gì, trả về cấu trúc ra sao, cần xác thực kiểu nào. Tệp này do máy đọc, thường nằm ngay trong kho mã và được kiểm soát phiên bản như mọi tệp nguồn khác. Trang tài liệu là thứ con người đọc, thường được sinh ra từ chính tệp đặc tả bằng một bộ dựng giao diện. Công cụ gọi thử là nơi bạn bắn một yêu cầu thật tới máy chủ và xem phản hồi trở về. Trang này chỉ làm việc đầu tiên, tức sinh ra tệp đặc tả, và cố tình dừng ở đó. Nó không gửi bất kỳ yêu cầu mạng nào tới endpoint bạn khai báo, cũng không dựng ra trang tài liệu có nút bấm. Hệ quả thực tế là bạn dùng trang này ở giai đoạn thiết kế, trước khi có dòng mã máy chủ nào, chứ không phải giai đoạn gỡ lỗi một endpoint đã chạy.
Đọc từng khối trong kết quả để biết mình đang có gì
Dòng đầu tiên khai phiên bản đặc tả là 3.0.3, đây là con số cố định và cũng là phiên bản được hầu hết bộ đọc hiện nay hỗ trợ tốt. Khối info chứa tên API bạn nhập cùng một số phiên bản mặc định là 1.0.0, phần phiên bản này không có ô để sửa nên bạn tự đổi sau khi sao chép. Nếu bạn chọn một kiểu xác thực khác none, một khối components xuất hiện ngay sau đó, bên trong là securitySchemes định nghĩa cách thức xác thực dùng chung cho cả tệp. Khối paths chứa đúng một đường dẫn, bên trong đường dẫn là đúng một phương thức viết thường, và bên trong phương thức là phần mô tả thao tác. Thao tác luôn có một dòng tóm tắt ghép từ phương thức viết hoa và đường dẫn, một mảng tham số, và một khối phản hồi. Khối phản hồi hiện chỉ có mã 200 với nội dung là một đối tượng chứa trường success kiểu luận lý, đây là chỗ bạn chắc chắn phải viết lại theo dữ liệu thật mà máy chủ trả về.
Cú pháp ba phần của ô tham số và quy tắc đánh dấu bắt buộc
Mỗi dòng trong ô tham số được tách thành ba phần bởi dấu hai chấm, theo thứ tự là tên tham số, vị trí xuất hiện và kiểu dữ liệu. Ví dụ dòng ghi page rồi hai chấm query rồi hai chấm integer sẽ tạo ra một tham số tên page nằm ở chuỗi truy vấn với kiểu số nguyên. Vị trí nhận các giá trị theo chuẩn là query cho chuỗi truy vấn, path cho biến nằm ngay trên đường dẫn, header cho tiêu đề yêu cầu và cookie cho bánh quy phiên. Có một quy tắc tự động cần nắm: tham số nào khai vị trí là path sẽ được đánh dấu bắt buộc, các vị trí còn lại đều để tùy chọn. Quy tắc này đúng với chuẩn OpenAPI vì một biến trên đường dẫn mà thiếu thì đường dẫn không còn hình thành được. Nếu bạn viết thiếu phần nào, giá trị mặc định sẽ được điền vào: tên thành id, vị trí thành query, kiểu thành string. Vì vậy một dòng chỉ ghi mỗi chữ limit vẫn tạo ra tham số hợp lệ nhưng kiểu chuỗi, hãy ghi đủ ba phần nếu muốn kiểu số.
Hai kiểu xác thực sinh ra những gì và cần sửa gì thêm
Ô xác thực nhận một trong ba giá trị. Gõ none thì đặc tả không có khối bảo mật nào, phù hợp với endpoint công khai. Gõ bearer thì khối định nghĩa chung mô tả một lược đồ tên BearerAuth theo kiểu http với cách thức bearer và định dạng mã thông báo là JWT, đồng thời trong phần mô tả thao tác xuất hiện một dòng tham chiếu tới lược đồ đó. Đây là cách khai báo phổ biến nhất cho các API dùng mã thông báo đăng nhập. Gõ apiKey, viết đúng chữ K hoa, thì lược đồ đổi thành ApiKeyAuth theo kiểu khóa API đặt ở tiêu đề với tên tiêu đề mặc định là X-API-Key. Cần lưu ý một điểm về cách công cụ xử lý: chỉ giá trị none mới tắt hẳn phần bảo mật, còn mọi chuỗi khác không phải apiKey đều được hiểu là bearer. Nghĩa là gõ nhầm thành apikey toàn chữ thường sẽ cho ra lược đồ Bearer chứ không phải khóa API. Nếu API của bạn đặt khóa ở tiêu đề tên khác, hãy sửa tên đó ngay sau khi sao chép đặc tả.
Cần bổ sung gì trước khi đưa vào kho mã, và khác gì các công cụ API còn lại
Đầu ra ở đây là bản khởi đầu chứ không phải bản hoàn chỉnh, có bốn chỗ gần như luôn phải bổ sung. Một là các mã phản hồi ngoài 200, tối thiểu nên có 400 cho dữ liệu gửi lên sai, 401 cho chưa xác thực và 404 cho không tìm thấy. Hai là lược đồ phản hồi thật thay cho đối tượng mẫu chỉ có một trường. Ba là các endpoint còn lại, vì mỗi lần sinh chỉ ra một đường dẫn với một phương thức, muốn nhiều thì sinh lần lượt rồi ghép các khối vào cùng một danh sách đường dẫn. Bốn là phần mô tả cho từng tham số để người đọc tài liệu hiểu ý nghĩa. Về phân định với các công cụ khác trên trang: bộ gọi thử Swagger và bộ gọi thử API đều làm việc ngược lại, tức lấy một endpoint đang chạy để bắn yêu cầu và xem phản hồi. Bộ sinh tài liệu API tạo ra trang cho người đọc chứ không tạo tệp cho máy đọc. Công cụ chuyển lược đồ GraphQL sang TypeScript phục vụ một kiểu API hoàn toàn khác, không có khái niệm đường dẫn hay phương thức. Còn bộ sinh lược đồ JSON chỉ mô tả hình dạng của một khối dữ liệu, không mô tả tầng giao vận HTTP bao quanh nó.
Câu hỏi thường gặp (FAQ)
Đặc tả OpenAPI là gì và ai là người đọc nó?
Là một tệp văn bản mô tả đầy đủ giao kèo của một API dạng REST, gồm các đường dẫn, tham số, cấu trúc dữ liệu gửi lên và trả về, cùng cách xác thực. Người đọc trực tiếp là máy: bộ dựng trang tài liệu, bộ sinh mã gọi API cho phía giao diện, bộ tạo máy chủ giả lập và các công cụ kiểm thử tự động đều nạp tệp này làm nguồn.
Kết quả sao chép ra có nạp thẳng vào bộ xem đặc tả được không?
Được với bản dạng JSON, vì nó đã đúng cấu trúc bắt buộc gồm khai báo phiên bản, khối thông tin và khối đường dẫn. Bộ xem sẽ dựng ra trang tài liệu có một endpoint. Nhưng đó mới là bộ khung, phần mô tả phản hồi còn ở dạng mẫu nên trang tài liệu chưa nói được gì hữu ích cho tới khi bạn viết lại lược đồ dữ liệu thật.
Ô tham số phải viết theo cú pháp nào?
Mỗi tham số một dòng, ba phần cách nhau bởi dấu hai chấm theo thứ tự tên, vị trí và kiểu dữ liệu. Vị trí nhận query, path, header hoặc cookie, kiểu nhận string, integer, number, boolean hoặc array. Dòng trống bị bỏ qua, phần thiếu được điền mặc định thành tên id, vị trí query và kiểu string.
Vì sao có tham số bị đánh dấu bắt buộc mà tôi không hề chọn?
Vì mọi tham số khai vị trí là path đều được đặt bắt buộc tự động. Đây là yêu cầu của chuẩn chứ không phải lựa chọn của công cụ: biến nằm trên đường dẫn mà vắng mặt thì đường dẫn không còn hợp lệ để định tuyến. Tham số ở chuỗi truy vấn, tiêu đề hay bánh quy phiên thì để tùy chọn, bạn tự sửa lại sau nếu muốn bắt buộc.
Tôi dán thân yêu cầu rồi mà đặc tả không thấy khối nào, do đâu?
Có hai nguyên nhân. Thứ nhất, khối thân yêu cầu chỉ được thêm khi phương thức thuộc nhóm ghi dữ liệu là post, put hoặc patch, còn get hay delete thì bị bỏ qua theo đúng thông lệ. Thứ hai, đoạn bạn dán phải là JSON hợp lệ, nếu sai cú pháp thì nó bị loại lặng lẽ mà không hiện thông báo lỗi nào, hãy kiểm lại dấu phẩy và dấu ngoặc kép.
Đầu ra YAML có dùng được ngay không?
Được. Gõ yaml vào ô định dạng thì công cụ dựng YAML theo đúng cấu trúc: mảng có gạch đầu dòng, object lồng nhau thụt lề hai khoảng trắng, và chuỗi được bọc nháy khi cần. Ba trường hợp bọc nháy đáng chú ý: khóa dạng số như 200 trong khối responses, đường dẫn chứa ngoặc nhọn như /orders/{id}, và chuỗi phiên bản như 1.0.0 nếu không bọc sẽ bị bộ đọc hiểu thành số. Kết quả đã được kiểm bằng bộ đọc YAML thật và parse ra đúng cấu trúc ban đầu, nên dán thẳng vào Swagger Editor hoặc lưu thành tệp openapi.yaml đều chạy.
Muốn mô tả nhiều endpoint trong cùng một tệp thì làm sao?
Mỗi lần sinh chỉ ra một đường dẫn kèm một phương thức. Cách làm là sinh lần lượt cho từng endpoint, rồi chép các khối đường dẫn vào chung một danh sách paths trong tệp cuối cùng, giữ lại một khối info và một khối components duy nhất ở đầu tệp. Nếu một đường dẫn có nhiều phương thức, chúng nằm cùng cấp bên trong đường dẫn đó.
Số phiên bản 1.0.0 sửa ở đâu?
Không có ô nhập cho trường này, nó được đặt cố định trong khối thông tin chung. Sau khi sao chép, bạn tự sửa con số đó trong tệp cho khớp với phiên bản API của mình. Đây cũng là chỗ nên bổ sung thêm phần mô tả tổng quan, thông tin liên hệ và điều khoản sử dụng nếu tệp sẽ được công bố ra ngoài.
Thêm các mã phản hồi lỗi như 400 hay 401 bằng cách nào?
Trong khối responses hiện chỉ có mục 200, bạn thêm các mục cùng cấp với nó, mỗi mục là một chuỗi mã trạng thái kèm phần mô tả và cấu trúc dữ liệu trả về. Nên thống nhất một khuôn dạng lỗi chung cho cả API rồi khai một lần trong phần định nghĩa chung, sau đó các endpoint tham chiếu tới, thay vì lặp lại ở từng chỗ.
Công cụ này khác bộ gọi thử Swagger và bộ gọi thử API ở chỗ nào?
Khác ở chiều làm việc. Hai công cụ kia cần một endpoint đang chạy để gửi yêu cầu thật lên mạng rồi hiển thị phản hồi, mã trạng thái và thời gian đáp ứng. Trang này không gửi yêu cầu nào cả, nó chỉ dựng ra văn bản mô tả endpoint. Bạn dùng nó ở giai đoạn thiết kế khi máy chủ còn chưa tồn tại, và dùng công cụ gọi thử ở giai đoạn kiểm tra.
Vậy còn khác gì bộ sinh tài liệu API?
Bộ sinh tài liệu tạo ra sản phẩm cho con người đọc, tức trang hoặc tệp trình bày có mục lục, ví dụ minh họa và cách diễn đạt dễ hiểu. Trang này tạo ra tệp cho máy đọc, dùng làm nguồn dữ liệu đầu vào. Trình tự hợp lý là sinh tệp đặc tả trước, hoàn thiện nó, rồi mới nạp vào một bộ dựng để có trang tài liệu.
Ô xác thực gõ sai chữ hoa chữ thường có ảnh hưởng gì không?
Có. Chỉ chuỗi none mới tắt hẳn phần bảo mật, và chỉ chuỗi apiKey viết đúng với chữ K hoa mới cho ra lược đồ khóa API đặt ở tiêu đề. Mọi chuỗi khác đều bị hiểu thành xác thực bằng mã thông báo Bearer. Nên sau khi sao chép, hãy liếc lại tên lược đồ trong đặc tả xem có đúng kiểu bạn định khai hay không.
Từ khóa liên quan
- openapi spec generator
- tạo file openapi 3.0
- swagger json online
- openapi json là gì
- cách viết đặc tả api
- đặc tả rest api
- khai báo parameters openapi
- securityschemes bearer jwt
- api key header x-api-key
- openapi requestbody json
- tài liệu api cho frontend
- thiết kế api trước khi code
- import json vào swagger ui
- openapi 3.0.3
- chuyển openapi json sang yaml
- khai báo query param openapi
- mẫu file openapi cho endpoint
- công cụ tạo swagger miễn phí
