Nếu bạn đã sử dụng Bruno, bạn đã biết sức hấp dẫn của nó. Các bộ sưu tập của bạn tồn tại dưới dạng các tệp .bru thuần túy trong kho lưu trữ Git của bạn, được kiểm soát phiên bản cùng với mã, không yêu cầu tài khoản đám mây. Đó là một giải pháp sạch sẽ, ưu tiên ngoại tuyến cho các máy khách API muốn sở hữu dữ liệu của bạn.
Nhưng sớm hay muộn, ai đó sẽ hỏi một câu hỏi mà Bruno không trả lời tốt: “Tài liệu ở đâu? Bạn có thể gửi cho tôi một liên kết được không?” Đó là lúc các nhóm gặp khó khăn. Bruno được xây dựng để gửi yêu cầu, chứ không phải để xuất bản một cổng tài liệu có thể chia sẻ. Hướng dẫn này trình bày trung thực về việc tạo tài liệu API bằng Bruno, những gì Bruno cung cấp cho bạn, những gì nó không cung cấp và cách tạo và lưu trữ tài liệu từ đặc tả của bạn khi bạn cần một URL thực để cung cấp cho người dùng.
Điều các nhóm thực sự cần từ tài liệu API
Trước khi đánh giá bất kỳ công cụ nào, việc xác định mục tiêu là rất hữu ích. Khi mọi người nói “tài liệu API”, họ thường đề cập đến ba điều hoạt động cùng nhau:
- Một URL có thể chia sẻ. Các nhà phát triển frontend, đối tác và QA cần đọc tài liệu mà không cần sao chép kho lưu trữ của bạn hoặc cài đặt một máy khách. Một liên kết trong Slack phải hoạt động ngay lập tức.
- Tài liệu luôn đồng bộ. Tài liệu không khớp với API thực còn tệ hơn là không có, vì nó khiến mọi người tự tin đi sai hướng. Tài liệu phải theo dõi đặc tả.
- Trải nghiệm “thử ngay” tương tác. Đọc mô tả endpoint là tốt; nhưng gửi một yêu cầu thực tế tới endpoint đã được tài liệu hóa, với xác thực và dữ liệu mẫu được điền sẵn, là điều biến tài liệu thành một tài liệu tham khảo có thể sử dụng được.
Đạt được cả ba điều này và tài liệu của bạn trở thành nguồn thông tin đáng tin cậy duy nhất. Bỏ lỡ một điều và mọi người sẽ quay lại hỏi trực tiếp bạn, điều này không thể mở rộng quy mô.
Câu chuyện tài liệu của Bruno
Hãy công bằng với Bruno, vì nó thực hiện tốt một số điều ở đây.
Các bộ sưu tập của Bruno có thể đọc được bởi con người. Định dạng .bru là văn bản thuần túy, vì vậy một kỹ sư duyệt kho lưu trữ có thể mở một tệp yêu cầu và xem phương thức, URL, tiêu đề và nội dung. Bruno cũng hỗ trợ một khối docs cho mỗi yêu cầu và một chế độ xem tài liệu Markdown bên trong ứng dụng, vì vậy bạn có thể đính kèm văn bản giải thích chức năng của một endpoint. Vì mọi thứ đều nằm trong Git, những ghi chú đó được xem xét trong các pull request giống như bất kỳ thay đổi nào khác. Đối với một nhóm nội bộ làm việc với codebase, đó là một hình thức tài liệu hợp lệ.
Khoảng trống thực sự là việc xuất bản. Bruno không có cổng tài liệu công khai được tích hợp, lưu trữ, tự động tạo. Không có nút “xuất bản” nào biến bộ sưu tập của bạn thành một trang web tại một URL ổn định với tên miền tùy chỉnh. Chế độ xem tài liệu trong ứng dụng chỉ hiển thị cho những người đã cài đặt Bruno và đã sao chép bộ sưu tập, đây chính xác là đối tượng ít cần tài liệu nhất.
Vì vậy, các nhóm phải ứng biến. Các giải pháp thay thế phổ biến bao gồm xuất bộ sưu tập hoặc tệp OpenAPI và đưa nó vào một trình tạo tài liệu tĩnh riêng biệt, thiết lập một trang tài liệu trong CI, hoặc duy trì một tệp README viết tay mà ai đó cập nhật theo trí nhớ. Những cách này có thể hoạt động, nhưng chúng bổ sung thêm một quy trình xây dựng để duy trì và một nơi thứ hai nơi thông tin có thể sai lệch. Tài liệu không còn là đầu ra hạng nhất của công cụ bạn dùng để kiểm thử; nó trở thành một dự án phụ.
Nguyên tắc docs-as-code
Một cách nghĩ rõ ràng hơn về điều này, và là điều mà người dùng Bruno đã phần nào tin tưởng: hãy coi tài liệu của bạn là một sản phẩm của đặc tả, chứ không phải một tạo tác riêng biệt.
Trong quy trình docs-as-code, API của bạn được mô tả một lần trong một đặc tả có thể đọc được bằng máy, thường là OpenAPI. Đặc tả đó nằm trong Git, được xem xét trong các pull request và đóng vai trò là hợp đồng. Tài liệu, máy chủ mô phỏng và SDK máy khách đều được tạo từ nó. Khi hợp đồng thay đổi, thay đổi được xem xét ở một nơi, và mọi thứ phụ thuộc đều tuân theo.
Ưu điểm là không có nhiệm vụ “cập nhật tài liệu” riêng biệt nào để quên. Tài liệu là một bản trình bày của đặc tả. Nếu đặc tả đúng và đã được xem xét, thì tài liệu cũng đúng. Đây là nguyên tắc mà Bruno hướng tới bằng cách giữ các bộ sưu tập trong Git, nhưng nó dừng lại trước bước xuất bản.
Thay vào đó, hãy tạo và lưu trữ tài liệu từ đặc tả của bạn
Đây là khoảng trống mà Apidog được xây dựng để lấp đầy. Apidog giữ nguyên mô hình tư duy lấy đặc tả làm trung tâm, thân thiện với Git, sau đó bổ sung phần mà Bruno còn thiếu: nó tạo ra một trang web tài liệu tương tác, được lưu trữ trực tiếp từ đặc tả của bạn, không yêu cầu quy trình xây dựng riêng biệt.
Hướng Apidog đến đặc tả OpenAPI của bạn và nó sẽ tự động tạo ra một cổng tài liệu. Kết quả là:
- Được lưu trữ tại một URL có thể chia sẻ, vì vậy bất kỳ ai có liên kết đều có thể đọc tài liệu mà không cần cài đặt bất cứ thứ gì.
- Có thể gắn trên một tên miền tùy chỉnh, vì vậy tài liệu có thể nằm tại
docs.yourcompany.comvà phù hợp với thương hiệu của bạn. - Tương tác, với một bảng điều khiển “thử ngay” tích hợp gửi các yêu cầu thực bằng cách sử dụng các tham số, tiêu đề và xác thực đã được tài liệu hóa.
- Được tạo từ đặc tả, vì vậy tài liệu phản ánh những gì API thực sự khai báo chứ không phải một bản sao viết tay có thể sai lệch.
Vì cùng một đặc tả cũng điều khiển việc kiểm thử và mô phỏng của Apidog, bạn không cần duy trì ba mô tả cho một API. Bạn mô tả nó một lần và tái sử dụng nó.
Hướng dẫn: từ đặc tả đến URL có thể chia sẻ
Đây là phiên bản ngắn gọn về việc xuất bản tài liệu từ một đặc tả OpenAPI.
| Bước | Hành động | Kết quả |
|---|---|---|
| 1 | Nhập hoặc viết đặc tả OpenAPI của bạn trong Apidog | Các endpoint, schema và ví dụ tự động được điền |
| 2 | Mở cài đặt tài liệu của dự án | Tài liệu được tạo từ đặc tả, sẵn sàng để cấu hình |
| 3 | Chọn khả năng hiển thị và (tùy chọn) tên miền tùy chỉnh | Tài liệu có thể công khai, riêng tư hoặc được bảo vệ bằng mật khẩu |
| 4 | Xuất bản | Một trang tài liệu trực tiếp, được lưu trữ được tạo tại một URL ổn định |
| 5 | Chia sẻ liên kết | Người dùng đọc tài liệu và chạy các yêu cầu “thử ngay” |
Nếu bạn đã có một bộ sưu tập Bruno, bạn có thể chuyển đổi nó sang OpenAPI trước, sau đó nhập đặc tả đó. Từ đó, bước xuất bản là như nhau. Điều quan trọng là việc tạo và lưu trữ tài liệu là một tính năng có sẵn, chứ không phải một quy trình bạn phải tự xây dựng.
Giữ tài liệu đồng bộ khi đặc tả thay đổi
Một URL tài liệu chỉ hữu ích nếu nó luôn chính xác. Chế độ lỗi với các thiết lập ứng biến là khi ai đó triển khai một thay đổi endpoint và quên cập nhật tài liệu.
Khi tài liệu được tạo từ đặc tả, rủi ro đó sẽ giảm đi. Bạn chỉnh sửa đặc tả, thay đổi đặc tả trải qua quá trình xem xét như bất kỳ thay đổi mã nào khác, và tài liệu đã xuất bản phản ánh trạng thái mới. Không có tài liệu song song nào cần nhớ. Thêm một trường vào schema phản hồi và nó sẽ xuất hiện trong tài liệu; ngừng hỗ trợ một endpoint và tài liệu cũng sẽ nói rõ điều đó. Công việc bạn đã làm để giữ hợp đồng chính xác cũng chính là công việc giúp tài liệu chính xác.
Đây là lợi ích thực tế của nguyên tắc docs-as-code: tính đúng đắn trở thành một tác dụng phụ của một quy trình làm việc mà bạn vẫn muốn có, thay vì một công việc riêng biệt phụ thuộc vào kỷ luật.
Câu hỏi thường gặp
Bruno có thể tạo và lưu trữ tài liệu API công khai không?
Bruno cung cấp các tệp bộ sưu tập .bru dễ đọc và chế độ xem tài liệu Markdown trong ứng dụng, cả hai đều được xem xét trong Git. Nó không bao gồm một cổng tài liệu công khai được tích hợp, lưu trữ, tự động tạo với một URL có thể chia sẻ. Để xuất bản tài liệu công khai từ Bruno, các nhóm thường xuất một đặc tả và chạy một trình tạo tài liệu tĩnh riêng biệt, điều này bổ sung thêm một quy trình để duy trì.
Làm cách nào để tôi có được một URL tài liệu có thể chia sẻ từ API của mình?
Mô tả API của bạn trong một đặc tả OpenAPI, sau đó sử dụng một công cụ tạo tài liệu được lưu trữ từ đó. Trong Apidog, bạn nhập đặc tả, cấu hình khả năng hiển thị, tùy chọn đính kèm một tên miền tùy chỉnh và xuất bản. Kết quả là một trang web tài liệu trực tiếp tại một URL ổn định, với một bảng điều khiển “thử ngay” tương tác, mà bạn có thể chia sẻ trực tiếp.
Tôi có phải từ bỏ các bộ sưu tập Bruno của mình để xuất bản tài liệu không?
Không. Bạn có thể chuyển đổi một bộ sưu tập Bruno hiện có sang OpenAPI và nhập đặc tả đó vào một công cụ tài liệu. Các endpoint, schema và ví dụ của bạn sẽ được giữ nguyên, và bạn giữ đặc tả dưới sự kiểm soát phiên bản. Việc chuyển đổi nằm ở lớp đặc tả, vì vậy các thói quen docs-as-code mà bạn đã xây dựng với Bruno vẫn được áp dụng.