Nếu bạn đang dùng Bruno, điểm mạnh rất rõ: collection nằm trong Git dưới dạng file .bru thuần văn bản, có thể review bằng pull request, không phụ thuộc cloud account và phù hợp với workflow offline-first.
Nhưng khi team cần trả lời câu hỏi “Tài liệu ở đâu? Gửi tôi một link được không?”, Bruno bắt đầu thiếu hụt. Bruno phù hợp để gửi request và quản lý collection, nhưng không được thiết kế như một cổng tài liệu API public có URL chia sẻ. Bài viết này hướng dẫn cách nhìn đúng vấn đề: Bruno hỗ trợ gì, thiếu gì, và cách tạo tài liệu API có thể publish từ đặc tả OpenAPI.
Điều một team thực sự cần từ tài liệu API
Khi nói “tài liệu API”, developer thường cần ba thứ:
URL có thể chia sẻ
Frontend, QA, partner hoặc backend khác có thể mở tài liệu ngay bằng một link, không cần clone repo hay cài Bruno.Tài liệu luôn đồng bộ với API
Nếu tài liệu lệch với implementation hoặc đặc tả, người dùng sẽ gọi sai endpoint, truyền sai field hoặc hiểu sai response.Khả năng “try it” trực tiếp
Tài liệu hữu ích hơn nhiều khi người đọc có thể gửi request thật với method, URL, header, auth và sample body đã được điền sẵn.
Nếu thiếu một trong ba yếu tố này, tài liệu sẽ nhanh chóng trở thành thứ mọi người bỏ qua và quay lại hỏi trực tiếp team API.
Bruno hỗ trợ tài liệu đến đâu?
Bruno làm tốt phần “API collection as code”.
Collection của Bruno là các file .bru có thể đọc được bằng text editor. Một request có thể chứa method, URL, header, body và metadata. Bruno cũng hỗ trợ block docs cho từng request, cho phép bạn thêm mô tả bằng Markdown bên trong app.
Ví dụ một file .bru có thể chứa phần mô tả như sau:
meta {
name: Get user by ID
type: http
}
get {
url: {{baseUrl}}/users/:id
}
params:path {
id: 123
}
docs {
# Get user by ID
Trả về thông tin chi tiết của một user theo ID.
}
Điểm mạnh của cách này:
- Request và mô tả nằm cùng nhau.
- Có thể version control trong Git.
- Có thể review thay đổi tài liệu trong pull request.
- Phù hợp với team nội bộ đã clone repo và dùng Bruno.
Nhưng vấn đề nằm ở bước publish.
Bruno không có sẵn một cổng tài liệu public được generate tự động, hosted sẵn, có URL ổn định và domain tùy chỉnh. Chế độ xem tài liệu trong app chỉ hữu ích cho người đã cài Bruno và đã có collection.
Vì vậy, nếu bạn cần gửi một link tài liệu cho người ngoài repo, Bruno không giải quyết trọn vẹn bài toán.
Các workaround thường gặp khi dùng Bruno
Một số team xử lý bằng cách:
- Export collection hoặc đặc tả OpenAPI.
- Dùng static documentation generator riêng.
- Build trang docs trong CI/CD.
- Viết README thủ công.
- Copy thông tin endpoint sang một wiki nội bộ.
Các cách này có thể chạy được, nhưng tạo thêm vấn đề:
- Có thêm pipeline cần maintain.
- Có thêm nơi tài liệu có thể bị lệch.
- Người sửa API phải nhớ cập nhật tài liệu ở nơi khác.
- Tài liệu không còn là output trực tiếp từ source of truth.
Nếu mục tiêu là tài liệu có URL public, ổn định và luôn đồng bộ, bạn nên đưa tài liệu về chung một nguồn: đặc tả API.
Nguyên tắc docs-as-code
Cách tiếp cận rõ ràng hơn là coi tài liệu là sản phẩm được tạo từ đặc tả, không phải một file riêng phải cập nhật thủ công.
Trong workflow docs-as-code, API được mô tả bằng một đặc tả có thể đọc bởi máy, thường là OpenAPI. Đặc tả này nằm trong Git, được review qua pull request và đóng vai trò như contract.
Từ cùng một đặc tả, bạn có thể tạo:
- Tài liệu API.
- Mock server.
- Test case.
- SDK hoặc client code.
- Schema validation.
Ví dụ một đoạn OpenAPI cơ bản:
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Get user by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
example: "123"
responses:
"200":
description: User detail
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "123"
name:
type: string
example: "Nguyen Van A"
Khi summary, parameters, responses hoặc schema thay đổi, tài liệu được generate từ đặc tả cũng thay đổi theo. Bạn không cần nhớ cập nhật một file docs riêng.
Bruno đã đi gần đến hướng này bằng cách giữ collection trong Git, nhưng phần publish tài liệu vẫn cần một công cụ khác.
Tạo và lưu trữ tài liệu từ đặc tả bằng Apidog
Đây là phần mà Apidog được xây dựng để giải quyết: giữ cách tiếp cận lấy đặc tả làm trung tâm, sau đó tạo tài liệu tương tác được lưu trữ trực tiếp từ đặc tả.
Workflow cơ bản:
- Chuẩn bị đặc tả OpenAPI.
- Import hoặc viết đặc tả trong Apidog.
- Kiểm tra endpoint, schema, example và auth.
- Mở phần cấu hình tài liệu.
- Chọn visibility.
- Publish tài liệu.
- Chia sẻ URL cho người dùng.
Kết quả là một cổng tài liệu:
- Có URL có thể chia sẻ.
- Có thể cấu hình domain tùy chỉnh.
- Có bảng “try it” để gửi request trực tiếp.
- Được tạo từ đặc tả, giảm rủi ro lệch tài liệu.
- Có thể dùng cùng đặc tả cho testing và mocking trong Apidog.
Hướng dẫn: từ OpenAPI đến URL tài liệu
Dưới đây là quy trình thực tế để publish tài liệu từ đặc tả OpenAPI.
| Bước | Hành động | Kết quả |
|---|---|---|
| 1 | Import hoặc viết đặc tả OpenAPI trong Apidog | Endpoint, schema và example được nhận diện |
| 2 | Kiểm tra lại method, path, params, body và response | Đặc tả sẵn sàng để generate tài liệu |
| 3 | Mở phần cài đặt tài liệu của project | Tài liệu được tạo từ đặc tả |
| 4 | Chọn visibility và tùy chọn domain tùy chỉnh | Tài liệu có thể public, private hoặc được bảo vệ |
| 5 | Publish | Có một trang tài liệu hosted tại URL ổn định |
| 6 | Chia sẻ link | Người dùng có thể đọc docs và chạy request “try it” |
Nếu bạn đã có collection Bruno, hướng đi hợp lý là:
Bruno collection
↓
Export hoặc chuyển đổi sang OpenAPI
↓
Import OpenAPI vào Apidog
↓
Generate và publish docs
↓
Chia sẻ URL
Điểm quan trọng là tài liệu được publish từ đặc tả, không phải từ một bản copy thủ công.
Giữ tài liệu đồng bộ khi API thay đổi
Một URL tài liệu chỉ có giá trị nếu nội dung trong đó chính xác.
Với workflow dựa trên đặc tả, bạn nên đặt quy tắc:
- Mọi thay đổi endpoint phải đi kèm thay đổi OpenAPI.
- Pull request cần review cả implementation và contract.
- Schema response phải được cập nhật khi field thay đổi.
- Endpoint deprecated phải được đánh dấu rõ trong đặc tả.
- Example request/response nên được cập nhật cùng lúc.
Ví dụ khi thêm field email vào response:
responses:
"200":
description: User detail
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
format: email
example: "user@example.com"
Khi đặc tả được cập nhật, tài liệu được generate từ đặc tả sẽ phản ánh field mới. Không cần một bước “nhớ cập nhật docs” riêng biệt.
Đây là lợi ích thực tế của docs-as-code: độ chính xác của tài liệu trở thành kết quả tự nhiên của workflow review contract.
Khi nào Bruno vẫn phù hợp?
Bruno vẫn là lựa chọn tốt nếu bạn cần:
- API client offline-first.
- Collection nằm trong Git.
- Không phụ thuộc tài khoản cloud.
- Review request bằng pull request.
- Tài liệu nội bộ đơn giản nằm cạnh request.
Nhưng nếu bạn cần:
- Gửi tài liệu cho người không dùng Bruno.
- Có URL public hoặc private ổn định.
- Có cổng docs tương tác.
- Có “try it” trong trình duyệt.
- Publish tài liệu từ OpenAPI mà không tự dựng pipeline riêng.
Thì bạn nên dùng một công cụ chuyên cho phần publish tài liệu từ đặc 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 có file collection .bru dễ đọc và chế độ xem tài liệu Markdown trong app. Các nội dung này có thể nằm trong Git và được review cùng code.
Tuy nhiên, Bruno không có sẵn một cổng tài liệu public được host tự động với URL có thể chia sẻ. Nếu muốn public docs từ Bruno, team thường phải export đặc tả rồi dùng một static docs generator hoặc workflow CI riêng.
Làm cách nào để có URL tài liệu có thể chia sẻ?
Cách thực tế là mô tả API bằng OpenAPI, sau đó dùng công cụ có khả năng generate và host tài liệu từ đặc tả đó.
Trong Apidog, bạn import đặc tả, cấu hình visibility, tùy chọn domain tùy chỉnh và publish. Sau đó bạn có một URL ổn định để gửi cho frontend, QA, partner hoặc người dùng API.
Tôi có phải bỏ Bruno để publish tài liệu không?
Không nhất thiết.
Bạn có thể tiếp tục dùng Bruno cho workflow collection nội bộ, sau đó chuyển collection hoặc contract sang OpenAPI để publish tài liệu bằng một công cụ khác. Phần quan trọng là giữ OpenAPI như nguồn contract chính, để tài liệu, test và mock không bị lệch nhau.
Tại sao không chỉ viết README?
README phù hợp cho hướng dẫn ngắn, ví dụ onboarding hoặc giải thích workflow. Nhưng với tài liệu API đầy đủ, README thường khó duy trì vì endpoint, schema, auth và response thay đổi liên tục.
Nếu tài liệu được generate từ OpenAPI, bạn giảm được rủi ro copy sai, quên sửa hoặc mô tả thiếu field.
Kết luận
Bruno rất mạnh ở workflow collection-as-code: request nằm trong Git, dễ review và phù hợp với team thích offline-first.
Nhưng khi cần tài liệu API có URL chia sẻ, hosted sẵn và tương tác, Bruno không giải quyết đầy đủ. Cách bền vững hơn là dùng OpenAPI làm contract, sau đó generate và publish tài liệu từ đặc tả đó.
Workflow nên là:
Đặc tả API trong Git
↓
Review bằng pull request
↓
Generate docs từ đặc tả
↓
Publish URL
↓
Người dùng đọc và thử request trực tiếp
Cách này giúp tài liệu trở thành một phần của quy trình phát triển API, thay vì một công việc phụ dễ bị quên.
Top comments (0)