Truy cập và cập nhật tài liệu của một API đã nhập

Khi bạn nhập một đặc tả, Restorm không chỉ tạo ra các yêu cầu: nó còn giữ lại tài liệu của API — mô tả, mô hình, sơ đồ bảo mật, ví dụ, kiểu liệt kê — và gắn nó vào thư mục biến do lần nhập tạo ra.

Truy cập tài liệu

Tab Docs của thư mục biến

Đây là khung nhìn chính. Hãy mở thư mục biến sinh ra từ lần nhập: thanh tab con của nó có một tab Docs, nằm cạnh Môi trường, Biến tùy chỉnh và Ghi chú.

Tab này chỉ xuất hiện nếu thư mục đến từ một lần nhập — một thư mục biến mà bạn tự tạo bằng tay thì không có tài liệu nào để hiển thị.

Các lối vào khác

Từ đâu	Bạn nhận được gì
Tab Docs của một yêu cầu	Tài liệu của riêng thao tác đó — không có mục lục cũng không có khối thông tin chung. Nó chỉ xuất hiện nếu tìm thấy thao tác trong đặc tả
Tab Docs của một thư mục thường	Tài liệu giới hạn trong các thao tác mà thư mục đó chứa
Tab con trang chủ của thư mục biến	Thẻ Xem tài liệu — “Duyệt tài liệu của API, các mô hình và các endpoint”
Màn hình chào mừng (thẻ API)	Liên kết nhanh Tài liệu
Công cụ tìm kiếm trên thanh tiêu đề	Một bản xem trước tài liệu khi di chuột lên một kết quả

Khung nhìn này chứa gì

Từ trên xuống dưới:

• tiêu đề của API và phần mô tả của nó;
• một khối thông tin: Version, Source format (kèm liên kết tới URL nguồn), Server (lược đồ, host, đường dẫn cơ sở), Contact, License, Terms of service, External docs;
• một mục cho mỗi nhãn, kèm mô tả của nhãn đó;
• một khối cho mỗi thao tác: phương thức và URL, phần tóm tắt, chấm nhóm, huy hiệu deprecated nếu có, phần Security (kiểu sơ đồ, luồng OAuth 2, phạm vi), và một Example payload thu gọn được;
• các bảng Parameters và Responses (các mã trạng thái được tô màu);
• Models — một đồ thị tương tác của các schema, điều hướng và phóng to được;
• Polymorphism — các tổ hợp oneOf / anyOf / allOf;
• Enums — các kiểu liệt kê, được gộp với những kiểu liệt kê của thư mục.

Note

Tên các phần này (Models, Enums, Parameters, Responses, Security, Example payload) được hiển thị bằng tiếng Anh trong mọi ngôn ngữ của ứng dụng. Ở đây chúng được giữ nguyên để bạn nhận ra chúng trên màn hình.

Tạo một yêu cầu từ tài liệu

Mỗi khối thao tác đều có một nút + Add tạo ra một yêu cầu đã được cấu hình sẵn cho thao tác đó. Đây là con đường ngắn nhất khi một lần nhập chỉ hoàn tất một phần, hoặc khi một thao tác vừa xuất hiện trong đặc tả.

Điều hướng và tìm kiếm

Một mục lục được neo ở bên phải — các phần Overview, Operations, Models, Enums — thu gọn và đổi kích thước được. Nhấp vào một mô hình sẽ cuộn tới đồ thị và căn nút tương ứng vào giữa.

Phím tắt	Tác dụng
Ctrl+F / Cmd+F	Mở phần tìm kiếm trong tài liệu
F3 / Enter	Kết quả khớp tiếp theo
Shift+F3 / Shift+Enter	Kết quả khớp trước đó
Esc	Đóng phần tìm kiếm

Một bộ đếm cho biết vị trí hiện tại trong các kết quả.

Cập nhật tài liệu

Một đặc tả luôn tiến hóa. Restorm biết cách đi lấy lại nguồn và áp dụng phần khác biệt — cả tài liệu lẫn yêu cầu — mà không ghi đè lên công sức của bạn.

Chỉ dành cho các lần nhập bằng URL

Việc đồng bộ lại chỉ có sẵn nếu thư mục được nhập từ một URL. Một lần nhập từ tệp hoặc bằng cách dán nội dung thì không ghi lại nguồn nào, và nút làm mới sẽ không xuất hiện: khi đó tab con trang chủ hiển thị “Thư mục này không được tạo từ một nguồn nhập được.”

URL này không sửa được về sau trong giao diện. Muốn đổi nguồn, hãy nhập lại.

Nút nằm ở đâu

Hai lối vào, tương đương nhau:

1. tab con trang chủ của thư mục biến, phần Cập nhật đặc tả — nó hiển thị URL, Lần nhập cuối và Lần kiểm tra cuối, và mang nút Làm mới;
2. nhấp chuột phải lên thư mục trong cây bên trái → Làm mới.

Không có cơ chế kiểm tra tự động

Restorm không theo dõi các đặc tả của bạn ở chế độ nền và sẽ không báo cho bạn biết có phiên bản mới. Việc kiểm tra luôn do bạn khởi động.

Điều gì diễn ra

1. Một cửa sổ “Đang làm mới đặc tả…” hiện ra trong lúc lấy dữ liệu. Các {{variables}} trong URL và trong header đều được giải quyết, và tuyến xác thực đã gắn sẽ được chạy trước.
2. Restorm so sánh một dấu vân tay của nguồn vừa lấy về với dấu vân tay đã lưu ở lần nhập cuối.
3. Không có gì thay đổi → “Đặc tả của API đã được cập nhật.”, và mọi việc kết thúc.
4. Có thay đổi (hoặc việc lấy dữ liệu thất bại) → trình hướng dẫn đồng bộ lại mở ra.

Trình hướng dẫn

• URL nguồn được hiển thị ở chế độ chỉ đọc.
• Một nút nhỏ cho phép gắn, sửa hoặc gỡ một tuyến xác thực, và một menu con Custom headers cho phép thêm các header cố định được gửi lại ở mỗi lần làm mới.
• Hai tab xem trước:
  • Routes — cây các thao tác tìm thấy trong phiên bản mới, có bộ lọc và phần chọn. Những thao tác đã có sẵn trong thư mục của bạn thì bị khóa và luôn được đánh dấu; bạn chỉ chọn xem sẽ thêm những thao tác mới nào;
  • Documentation — tài liệu của phiên bản mới, ở chế độ chỉ đọc, trước khi bạn xác nhận.
• Nút xác nhận hiển thị số thao tác mới đã chọn, ví dụ Apply update (3).

Note

Hiện tại trình hướng dẫn được hiển thị bằng tiếng Anh bất kể ngôn ngữ của ứng dụng (“Refresh from source”, “Apply update”, các tab “Routes” và “Documentation”). Vì vậy các nhãn tiếng Anh được giữ nguyên ở đây.

Cái gì bị thay đổi, và cái gì thì không

Đây là điểm quan trọng: đặc tả có thẩm quyền trên những gì nó mô tả, còn bạn có thẩm quyền trên phần còn lại.

Phần tử	Hành vi
Tên của một yêu cầu	Không bao giờ bị thay đổi
Phương thức và URL	Không bao giờ bị thay đổi
Các tham số, header và tham số đường dẫn đã có	Được giữ nguyên — giá trị, mô tả, trạng thái bật/tắt
Các tham số được đặc tả thêm vào	Được thêm, với giá trị mặc định của đặc tả hoặc để trống
Các tham số bị đặc tả bỏ đi	Vẫn được giữ trên yêu cầu
Thao tác mới	Được thêm vào đúng chỗ mà một lần nhập mới sẽ đặt nó (kể cả thư mục nhãn)
Thao tác bị đặc tả đánh dấu lỗi thời	Được báo hiệu; nó hiện ra mờ đi trong cây
Thao tác đã biến mất khỏi đặc tả	Được báo là đã gỡ bỏ; nó hiện ra gạch ngang trong cây, vẫn chạy được và không bao giờ bị xóa
Tài liệu API và các kiểu liệt kê	Bị thay thế hoàn toàn bằng phiên bản mới — đây chính là thứ làm mới tab Docs

Không có gì bị xóa khỏi cây của bạn: một thao tác biến mất khỏi nguồn thì được đánh dấu, chứ không bị xóa.

Nếu nguồn yêu cầu xác thực

Một phản hồi 401 hoặc 403 sẽ mở trình hướng dẫn kèm thông báo lỗi hiển thị nguyên văn (ví dụ HTTP 401: Unauthorized). Hãy gắn một tuyến xác thực hoặc thêm các header cố định, rồi phần xem trước sẽ chạy lại.

Các định dạng đồng bộ lại được

Mười hai định dạng có cơ chế đồng bộ lại: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC và Smithy.

Với tất cả những định dạng còn lại, một lần nhập mới sẽ tạo ra một cây mới. Danh sách đầy đủ nằm trong Cập nhật từ nguồn.