Tuyến & CRUD

Các tuyến là các điểm truy cập của API của bạn. Chúng được gom theo tài nguyên, và bạn có thể viết chúng thủ công hoặc sinh chúng từ một mô hình.

Định nghĩa một tuyến

Một tuyến mang một phương thức, một đường dẫn, các tham số và các phản hồi. Đường dẫn dùng cú pháp {{param}} của Restorm: ngay khi bạn gõ {{id}} trong đường dẫn, tham số tương ứng xuất hiện; xóa nó đi sẽ loại bỏ nó.

Các tham số

Tab Định nghĩa của một tuyến liệt kê các tham số của nó — các tham số đường dẫn (được tạo từ các placeholder {{param}}) và các tham số truy vấn / header mà bạn thêm bằng Thêm một tham số. Mỗi tham số mang một tên, một vị trí (in), tính bắt buộc của nó, một mô tả và, tùy chọn, một ví dụ.

Ô Kiểu là một combo: chọn một kiểu nguyên thủy (string, integer, number, boolean) hoặc một trong các enum có tên của thiết kế chỉ bằng một nhấp. Với các trường hợp phức tạp hơn, chọn Advanced… để mở một cửa sổ nhỏ nơi bạn có thể:

• biến tham số thành một mảng và chọn kiểu phần tử của nó (array<string>, …) — một tham số truy vấn nhiều giá trị;
• cho nó các giá trị enum nội tuyến (tập được phép, liệt kê dưới dạng huy hiệu) khi nó không được định kiểu bằng một enum có tên;
• Trích xuất thành enum có tên — nâng các giá trị nội tuyến này thành một enum dùng chung (xem Mô hình & enum).

Một tham số cũng có thể được liên kết với một thuộc tính mô hình (cột Liên kết mô hình), kế thừa kiểu của thuộc tính đó, hoặc được đánh dấu ngừng dùng. Mỗi tham số — kiểu của nó, enum của nó, việc ngừng dùng của nó — đều đi vào tài liệu được sinh và vào mọi phép chiếu giao thức.

Sinh CRUD

Từ các thiết lập của một mô hình, Sinh CRUD tạo bằng một nhấp một nhóm tuyến được đặt tên theo dạng số nhiều của mô hình, với sáu tuyến:

Tuyến	Phương thức & đường dẫn	Phản hồi
Liệt kê	GET / (phân trang)	200
Lấy về	GET /{{id}}	200 · 404
Tạo	POST /	201
Thay thế	PUT /{{id}}	200 · 404
Cập nhật	PATCH /{{id}}	200 · 404
Xóa	DELETE /{{id}}	204 · 404

Danh sách được phân trang (offset, 20 phần tử mặc định, tối đa 100). Mỗi {{id}} được tự động liên kết với định danh của mô hình.

Hộp thoại Sinh CRUD cung cấp hai tùy chọn:

• Thay thế các tuyến hiện có — để tránh trùng lặp nếu bạn sinh lại.
• Bảo vệ các tuyến ghi bằng xác thực — khi đó việc tạo, việc thay thế, việc cập nhật và việc xóa yêu cầu một token (bearer), trong khi các thao tác đọc vẫn công khai.

Nó cũng nhắc rằng CRUD được phục vụ trong từng giao thức: tuyến REST, truy vấn và mutation GraphQL, phương thức gRPC, tập thực thể OData và thao tác SOAP (xem Phục vụ thiết kế dưới dạng mock).

Sinh các tuyến tìm kiếm

Với mỗi thuộc tính được đánh dấu searchable, Sinh các tuyến tìm kiếm thêm một tham số truy vấn liên kết với tuyến liệt kê của mô hình (và tạo tuyến đó nếu nó chưa tồn tại).

Xác thực

Xác thực được thiết lập ở ba cấp: một giá trị mặc định của thiết kế, một xác thực bắt buộc theo nhóm, và một ghi đè theo tuyến (kế thừa từ mặc định của nhóm). Các chế độ khả dụng là Không có, Bearer (JWT), Khóa API (header) và Basic.

Các thẻ

Các thẻ nhóm các tuyến lại cho tài liệu và cho việc xuất OpenAPI. Chúng tồn tại ở hai cấp: một tuyến mang các thẻ của riêng nó (tab Định nghĩa của nó), và một nhóm mang các thẻ dùng chung (các thiết lập của nó) áp dụng cho mỗi tuyến trong nhóm. Các thẻ hiệu lực của một tuyến là hợp của cả hai — nên một thẻ chung cho cả một nhóm tốt nhất chỉ nên đặt một lần trên nhóm. Khi bạn chuyển một API đã nhập thành một thiết kế, một thẻ hiện diện trên tất cả các tuyến của một nhóm sẽ tự động được nâng lên nhóm.

Việc ngừng dùng

Một tuyến (giống như một thuộc tính hay một tham số) có thể được đánh dấu ngừng dùng từ Thiết lập của nó. Một tuyến ngừng dùng hiển thị bị làm mờ trong danh sách Tuyến và trong các client được sinh, và mang một cảnh báo ngừng dùng trên tab của nó. Cờ này lan vào mọi phép chiếu giao thức — deprecated của OpenAPI, chỉ thị @deprecated của GraphQL, các bộ mô tả SOAP và gRPC, và siêu dữ liệu OData — để những người tiêu thụ bất kỳ giao thức nào được phục vụ đều thấy nó.