Trang này được dịch bởi Cloud Translation API.

Sử dụng SmartDocs để ghi lại các API

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến Tài liệu về Apigee X. thông tin

Dịch vụ hỗ trợ các mô-đun Apigee cho cổng thông tin dành cho nhà phát triển dựa trên Drupal 7 sẽ ngừng hoạt động kể từ ngày 2 tháng 1 năm 2023. Mặc dù các cổng thông tin dựa trên Drupal 7 vẫn sẽ hoạt động, nhưng Apigee sẽ không phát hành bản vá bảo mật cho các mô-đun Drupal 7 của họ hoặc gửi Cập nhật PHP hoặc Drupal 7 cho khách hàng OPDK sau ngày 2 tháng 1 năm 2023.

Vì các mô-đun Apigee Drupal 7 phụ thuộc vào PHP 7.4, nên bạn có thể cũng chịu ảnh hưởng của việc kết thúc bản vá bảo mật dành cho PHP 7.4 sắp diễn ra vào cuối tháng 11 năm 2022. Drupal 7 sẽ đến ngày hết hạn sử dụng vào ngày 23 tháng 11 năm 2023.

Bạn nên nâng cấp lên Drupal 10. Vui lòng trao đổi với nhóm của bạn và đánh giá các lựa chọn nâng cấp để tránh mọi rủi ro bảo mật tiềm ẩn. Để biết thêm thông tin về việc chuyển sang Drupal 10, hãy xem bài viết Xây dựng cổng thông tin bằng Drupal 9.

SmartDocs cho phép bạn ghi lại các API của mình trên cổng thông tin dành cho nhà phát triển Drupal 7 theo cách giúp Tài liệu API có tính tương tác đầy đủ. Tài liệu tương tác có nghĩa là người dùng cổng có thể:

Đọc về các API của bạn
Gửi yêu cầu trực tiếp đến API của bạn
Xem phản hồi trực tiếp được API trả về

Bằng cách tạo tài liệu có tính tương tác về API của bạn, bạn giúp người dùng cổng dễ dàng tìm hiểu, kiểm thử và đánh giá các API của bạn.

API quản lý Edge là một API RESTful cho phép bạn truy cập vào Dịch vụ API bằng bất kỳ máy khách HTTP. Apigee sử dụng SmartDocs để tạo tài liệu có tính tương tác cho việc quản lý Edge API. Xem tài liệu về API đó tại đây.

Ví dụ về cổng thông tin SmartDocs

Để sử dụng SmartDocs, bạn phải có cổng Dịch vụ dành cho nhà phát triển Apigee. Để biết thêm thông tin, hãy xem Tạo nhà phát triển cổng thông tin.

Từ trang chủ cổng thông tin dành cho nhà phát triển của bạn, hãy nhấp vào API ở thanh điều hướng trên cùng để xem trang Tài liệu API.

Có hai API được nêu trên cổng thông tin: Ví dụ về Hello World và Pet Store.

Hello World API được tạo từ mục tiêu mô phỏng OpenAPI Thông số kỹ thuật, mocktarget.yaml. Để biết thêm thông tin, hãy tham khảo https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

API Ví dụ về Cửa hàng thú cưng được tạo từ bản minh hoạ cổ điển về cửa hàng thú cưng.

Khám phá Hello World API:

Nhấp vào Hello World API. Trang tóm tắt Hello World API sẽ được hiển thị:
Nhấp vào Xem lời tự động viên API. SmartDocs cho tài nguyên này là được hiển thị:
Nhấp vào Gửi yêu cầu này.

Xem phản hồi được trả về:

HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>

Nhấp vào thẻ Request (Yêu cầu) để xem yêu cầu hoặc nhấp vào cURL để xem lệnh gọi cURL tương ứng.

Cách ghi lại API của bạn bằng cách sử dụng SmartDocs

SmartDocs biểu thị API của bạn bằng cách sử dụng một mô hình, trong đó mô hình chứa tất cả thông tin về API của bạn. Cổng thông tin trích xuất thông tin về API của bạn từ mô hình để hiển thị các trang tài liệu trên cổng thông tin dưới dạng các nút Drupal, trong đó mỗi nút Drupal tương ứng vào một trang tài liệu trên cổng thông tin.

Sau đây là các bước chung mà bạn thực hiện để sử dụng SmartDocs:

Định cấu hình mô-đun Drupal SmartDocs trên cổng thông tin.
Tạo một mô hình SmartDocs.
Thêm các API vào mô hình từ tệp WADL, OpenAPI (trước đây là Swagger) hoặc theo cách thủ công.
Kết xuất mô hình dưới dạng một tập hợp các nút Drupal. Mỗi nút Drupal chứa thông tin về một API. Ví dụ: nếu một tài nguyên trong API của bạn hỗ trợ cả POST và yêu cầu PUT, SmartDocs tạo một nút Drupal riêng biệt cho POST và PUT.
Xuất bản các nút Drupal. Sau khi trang web được xuất bản, người dùng cổng thông tin có thể xem và tương tác với API của bạn.
Chỉnh sửa các nút Drupal, trước hoặc sau khi xuất bản. Bạn có thể chỉnh sửa các nút Drupal bằng cách sử dụng trình chỉnh sửa Drupal hoặc bằng cách chỉnh sửa tệp WADL gốc hoặc Thông số kỹ thuật OpenAPI. Khi bạn chỉnh sửa xong tệp WADL hoặc Thông số kỹ thuật OpenAPI, hãy nhập đưa trở lại vào mô hình dưới dạng một bản sửa đổi mới, sau đó hiển thị và xuất bản các thay đổi của bạn.
Bật TLS. Vì SmartDocs gửi thông tin xác thực đến như một phần trong quá trình gửi yêu cầu tới API, bạn nên bật TLS trên cổng thông tin của mình để hãy đảm bảo rằng những thông tin đăng nhập đó đều được bảo mật. Trong môi trường kiểm thử và sản xuất cổng thông tin, Apigee cung cấp chứng chỉ TLS cần thiết để đưa ra các yêu cầu https://. Tuy nhiên, trước khi đi trực tiếp với cổng thông tin của bạn, bạn phải lấy chứng chỉ TLS của riêng mình và bật TLS. Để biết thêm thông tin, hãy xem Sử dụng TLS trên cổng thông tin.

Giới thiệu về các mô hình và mẫu SmartDoc

Khi bạn tạo một mô hình trong cổng thông tin, mô hình đó sẽ thực sự được lưu trữ trong Edge chứ không phải trong Drupal. Mô hình là một khối JSON lớn có tên nội bộ (chẳng hạn như "my-smartdocs-api") và định nghĩa cấu trúc của một API. Mặt khác, cổng thông tin của bạn kết xuất mô hình dưới dạng HTML và cung cấp giao diện chỉnh sửa cho mô hình. Mọi nội dung cập nhật đối với API trong cổng sẽ tự động bị đẩy trở lại mô hình nguồn.

Được lưu trữ trong tổ chức	Được lưu trữ trong Drupal
model	các mẫu Các nút Drupal có chức năng chỉnh sửa

Được lưu trữ trong tổ chức

Được lưu trữ trong Drupal

model

các mẫu

Các nút Drupal có chức năng chỉnh sửa

Giả sử rằng bạn có nhiều cổng trong tổ chức của mình (ví dụ: cổng phát triển, cổng và giai đoạn phát hành công khai). Trong Pantheon, bạn sẽ di chuyển một cổng thông tin từ môi trường này sang môi trường khác. Mỗi thực thể của có vẻ như cổng chứa mô hình riêng, nhưng tất cả đều thực sự tham chiếu đến nguồn mô hình. Nếu bạn chỉnh sửa API trong kênh phát triển, mô hình sẽ được cập nhật và các thay đổi sẽ xuất hiện trong phiên bản chính thức. Tương tự, nếu bạn xoá một mô hình trong nhà phát triển, thì nguồn sẽ bị xoá và mô hình đó không còn tồn tại trong sản xuất.

Mẫu kiểm soát giao diện của SmartDocs của bạn cũng như các mẫu đó (được quản lý bởi Tay cầm và tệp CSS) được lưu trữ cùng với từng phiên bản cổng thông tin. Vì vậy, về mặt lý thuyết, mỗi cổng có thể và sử dụng một mẫu duy nhất cho từng mô hình. Tuy nhiên, một trong những tiện lợi của khung kết xuất là mẫu mặc định (mẫu mặc định của Apigee hoặc mẫu mà bạn cung cấp) sẽ tự động áp dụng cho từng mô hình.

Sơ đồ dưới đây cho thấy mối quan hệ giữa các mô hình và cổng. Mũi tên màu xanh lục cho biết tự động đồng bộ hoá.

Lệnh cURL sau đây liệt kê tất cả các mô hình trong tổ chức của bạn:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Định cấu hình mô-đun SmartDocs

Apigee triển khai SmartDocs dưới dạng một mô-đun Drupal tuỳ chỉnh. Hãy sử dụng quy trình sau để định cấu hình mô-đun SmartDocs.

Cách định cấu hình mô-đun SmartDocs:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Modules (Mô-đun) trong trình đơn quản trị Drupal. Danh sách tất cả các mô-đun Drupal đã cài đặt sẽ xuất hiện.
Bật mô-đun SmartDocs.
Lưu cấu hình.
Chọn Modules (Mô-đun) trong trình đơn quản trị của Drupal.
Chọn SmartDocs -> Quyền và đảm bảo rằng "Thực hiện quản trị" nhiệm vụ cho mô-đun SmartDocs" dành cho "Quản trị viên" vai trò được bật.
Chọn Cấu hình > Cổng thông tin cho nhà phát triển trong quản trị của Drupal .
Đặt Thời gian chờ kết nối và Thời gian chờ yêu cầu thành 16 giây.
Lưu cấu hình.
Định cấu hình chế độ cài đặt URL:
1. Chọn Cấu hình > Tìm kiếm và siêu dữ liệu > Bí danh URL > Settings (Cài đặt) trên trình đơn Drupal.
2. Đặt Độ dài bí danh tối đa và Thành phần tối đa độ dài thành 255.
3. Mở rộng phần Dấu câu.
4. Đối với Dấu ngoặc nhọn trái ({) và Dấu ngoặc nhọn phải (}), chọn Không có hành động nào (không thay thế).
5. Nhấp vào Lưu cấu hình.
Nếu cổng thông tin dành cho nhà phát triển của bạn hiển thị với người dùng trong mạng nội bộ mà không có quyền truy cập vào Internet hoặc nếu một nhóm nhỏ API của bạn ở trên mạng riêng, hãy định cấu hình API SmartDocs proxy như sau:
1. Chọn Cấu hình > SmartDocs trong Quản trị Drupal .
2. Mở rộng Cài đặt nâng cao.
3. Cập nhật trường URL proxy SmartDocs như sau: <host>/smartdocs/v1/sendrequest.
  Trợ giúp nội tuyến phải cung cấp giá trị bắt buộc cho môi trường của bạn. Ví dụ:
  https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest
  
  Trường này được mặc định là https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
4. Nhấp vào Lưu cấu hình.

Tạo mô hình

Mô hình chứa tất cả thông tin về cách trình bày API của bạn. Bạn có thể xác định nhiều mô hình trên cổng thông tin để hỗ trợ các API khác nhau hoặc nhóm tất cả API của bạn vào một mô hình.

Mỗi mô hình chỉ định một tên nội bộ duy nhất, tên này cũng xác định URL cơ sở của các nút Drupal đã tạo. URL của mỗi nút Drupal có dạng:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

trong đó:

drupalBasePath: URL cơ sở của cổng thông tin của bạn.
internalName: Tên nội bộ của mô hình.
httpMethod: Phương thức HTTP của API, chẳng hạn như get, put, post hoặc xoá.
resourcePath: Đường dẫn tài nguyên.

Ví dụ: nếu bạn chỉ định tên nội bộ là 'mymodel', thì URL cho phần tử được tạo Nút Drupal cho yêu cầu GET tới tài nguyên có tên "/books" là:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Để tạo mô hình

Khi bạn tạo một mô hình, mô hình đó sẽ được lưu trữ trong tổ chức Edge dưới dạng nguồn của API cấu trúc. Để biết thêm thông tin, hãy xem bài viết Giới thiệu về các mô hình SmartDoc và mẫu.

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartDocs trong quản trị Drupal .
Chọn Mô hình mới ở đầu trang.
Nhập vào các trường sau:
- Tên: Tên mô hình sẽ được hiển thị trên trang web.
- Tên nội bộ: Khi bạn nhập Tên, tên nội bộ tên hiển thị. Tên nội bộ cho mô hình phải là duy nhất trong số tất cả các mô hình. Tên nội bộ chỉ được chứa chữ thường, số và dấu gạch nối không có dấu cách. Chọn Chỉnh sửa để chỉnh sửa tên này.
- Nội dung mô tả: Nội dung mô tả về mô hình.
Chọn Tạo mô hình.

Sau khi tạo mô hình, bạn sẽ được chuyển hướng đến trang của mô hình. Từ đó, bạn có thể sử dụng Trình đơn thả xuống bx để:

Nhập tệp WADL mô tả API của bạn hoặc chỉ định URL của một OpenAPI Thông số kỹ thuật mô tả API của bạn.
Thêm bản sửa đổi vào mô hình
Sửa đổi Cài đặt mô hình, bao gồm các biểu định kiểu được sử dụng bởi mô hình.
Xuất mô hình sang một tệp.
Xoá mô hình.

Thêm API vào mô hình

Bạn có thể thêm API vào mô hình bằng cách:

Nhập tệp WADL chứa định nghĩa API
Nhập thông số kỹ thuật OpenAPI (OpenAPI 2.0 hoặc 1.2)
Tạo tài nguyên và phương thức theo cách thủ công

Bạn cũng có thể nhập tệp JSON SmartDocs vào một mô hình. Tệp này thường được tạo bởi đầu tiên xuất mô hình hiện có, chỉnh sửa tệp, sau đó nhập nội dung cập nhật. Để biết thêm thông tin, xem "Xuất và nhập một mô hình" bên dưới.

Video: Xem video ngắn để tìm hiểu cách thêm API vào mô hình SmartDocs bằng cách nhập một Thông số kỹ thuật OpenAPI.

Nhập WADL

Sau khi bạn đã tạo thành công một mô hình, hãy nhập tệp WADL mô tả API của bạn. Mỗi khi nhập tệp WADL, bạn sẽ tự động tạo bản sửa đổi mới của mô hình.

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartDocs trong Drupal trình đơn quản trị.
Chọn người mẫu bạn muốn cập nhật.
Trong mục Vận hành, hãy chọn Nhập.
Chọn WADL trong trình đơn thả xuống Chọn định dạng trên Trang nhập SmartDocs.
Chọn Tệp hoặc URL trong nút Tải lên Loại thả xuống.
1. Nếu bạn chọn Tệp, hãy duyệt đến tệp WADL.
2. Nếu bạn chọn URL, hãy chỉ định URL của tệp WADL.
Nhấp vào Import (Nhập) để nhập vào mô hình. Bạn có thể làm điều này ngay bây giờ kết xuất mô hình.
Bạn được chuyển hướng đến trang thông tin của mô hình nơi bạn hiện có thể kết xuất mô hình.

Nhập OpenAPI Quy cách

Sau khi tạo mô hình thành công, bạn có thể nhập OpenAPI (trước đây là Swagger) Thông số kỹ thuật. Edge hỗ trợ OpenAPI phiên bản 1.2 và 2.0.

OpenAPI sử dụng các tệp chứa đối tượng JSON để mô tả một API. Mỗi khi bạn nhập Thông số kỹ thuật OpenAPI, bạn sẽ tự động tạo bản sửa đổi mới của mô hình.

Cách nhập một Thông số kỹ thuật OpenAPI:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong ứng dụng Trình đơn quản trị Drupal.
Chọn người mẫu bạn muốn cập nhật.
Trong mục Vận hành, hãy chọn Nhập.
Chọn Swagger JSON hoặc Swagger YAML trong Trình đơn thả xuống Chọn định dạng trên trang nhập SmartDocs.
Chọn Tệp hoặc URL trong Trình đơn thả xuống Loại tệp tải lên (bạn phải chọn URL cho OpenAPI 1.2).
1. Nếu bạn chọn File (Tệp), hãy duyệt đến OpenAPI Thông số kỹ thuật.
2. Nếu bạn chọn URL, hãy chỉ định URL của OpenAPI Thông số kỹ thuật.
Nhấp vào Import (Nhập) để nhập vào mô hình.
Bạn được chuyển hướng đến trang thông tin của mô hình nơi bạn hiện có thể kết xuất mô hình.

Tạo tài nguyên theo cách thủ công và phương thức

Nếu không có tệp WADL hoặc thông số kỹ thuật OpenAPI thể hiện API của mình, bạn có thể thêm API vào mô hình của bạn theo cách thủ công. Ngoài ra, nếu bạn sử dụng tệp WADL hoặc Thông số kỹ thuật OpenAPI để tạo mô hình của mình, bạn có thể sử dụng quy trình này để chỉnh sửa API, bao gồm cả việc thêm API mới, sau khi nhập.

Cách thêm API theo cách thủ công:

Tạo một bản sửa đổi mới của mô hình.

Khi tạo bản sửa đổi, bạn chỉ định đường dẫn cơ sở duy nhất của tất cả API trong mô hình, tức là tất cả API trong một mô hình có cùng đường dẫn cơ sở. Ví dụ: chỉ định đường dẫn cơ sở dưới dạng:

https://myCompany.com/v1

Khi bạn thêm tài nguyên vào mô hình, chúng sẽ mở rộng đường dẫn cơ sở.
Xác định một hoặc nhiều tài nguyên cho mô hình. Đường dẫn tài nguyên kết hợp với đường dẫn cơ sở của bản sửa đổi mô hình để chỉ định URL đầy đủ của tài nguyên. Ví dụ: nếu tài nguyên của bạn xác định đường dẫn "/login", URL đầy đủ của tài nguyên là:

https://myCompany.com/v1/login
Xác định một hoặc nhiều phương thức cho từng tài nguyên. Một phương thức chỉ định động từ HTTP có thể là được gọi trên tài nguyên. Ví dụ: đối với lệnh "/login" bạn hỗ trợ POST để đăng nhập và DELETE để đăng xuất. Tài nguyên này không hỗ trợ các động từ HTTP khác, chẳng hạn như PUT hoặc GET. Do đó, hãy xác định 2 phương thức cho tài nguyên, một phương thức cho thao tác POST và một phương thức cho thao tác DELETE.

Phương thức này sử dụng URL tài nguyên từ tài nguyên mẹ. Do đó, tất cả các phương pháp có cùng URL được xác định trong một tài nguyên duy nhất trong SmartDocs.

Theo nguyên tắc chung:

Tạo một mô hình SmartDocs riêng cho từng đường dẫn cơ sở riêng biệt trong API của bạn.
Xác định một tài nguyên SmartDocs khác nhau cho từng tài nguyên riêng biệt trong API của bạn.
Xác định phương thức SmartDocs riêng cho từng động từ HTTP mà tài nguyên hỗ trợ.

Tạo bản sửa đổi mới của mô hình

Bạn chỉ có thể thêm tài nguyên vào bản sửa đổi hiện có của mô hình. Nếu mô hình đã có bản sửa đổi, bạn có thể thêm tài nguyên của mình. Nếu mô hình này là mô hình mới và không có bản sửa đổi nào, hãy tạo một mô hình bản sửa đổi này.

Cách tạo bản sửa đổi mới của mô hình:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mẫu xe mà bạn muốn cập nhật, hãy chọn Thêm bản sửa đổi trong Hoạt động.
Trên trang Thêm bản sửa đổi API, hãy nhập những thông tin sau:
- Tên hiển thị: Tên của bản sửa đổi xuất hiện trong cổng thông tin.
- Mã phiên bản: Giá trị nhận dạng ngắn của bản sửa đổi.
- Nội dung mô tả: Nội dung mô tả về bản sửa đổi.
- URL cơ sở: URL cơ sở của tất cả API trong bản sửa đổi mô hình. Đáp có thể sử dụng các URL cơ sở khác nhau cho từng bản sửa đổi. Ví dụ: bạn thêm một phiên bản trong URL cơ sở. Đối với bản sửa đổi mô hình đầu tiên, URL cơ sở là:
  https://myCompany.com/v1
  Đối với lần sửa đổi tiếp theo, URL cơ sở có thể là:
  https://myCompany.com/v2
Chọn Thêm bản sửa đổi. Bạn sẽ được chuyển hướng đến trang sửa đổi của mô hình. Giờ đây, bạn có thể xác định các tài nguyên trên mô hình.

Xác định tài nguyên

Tài nguyên chỉ định URL đầy đủ của một API. Khi xác định tài nguyên, bạn chỉ định Đường dẫn tài nguyên này được kết hợp với URL cơ sở trong bản sửa đổi mô hình để tạo URL đầy đủ của tài nguyên.

Để xác định tài nguyên:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình mà bạn muốn cập nhật, trong phần Hoạt động, hãy chọn API Các bản sửa đổi để xem tất cả các bản sửa đổi của mô hình.
Chọn một bản sửa đổi để chỉnh sửa.
Trên trang bản sửa đổi, hãy chọn Add Resource (Thêm tài nguyên) trên trình đơn thả xuống.
Trên trang Add Resource (Thêm tài nguyên), hãy nhập những thông tin sau:
- Tên hiển thị: Tên của tài nguyên.
- Đường dẫn: Đường dẫn tài nguyên, bắt đầu bằng "/". Giá trị của Đường dẫn được kết hợp với URL cơ sở của bản sửa đổi mô hình để tạo URL đầy đủ của tài nguyên.
- Nội dung mô tả: Nội dung mô tả của tài nguyên.
- Thông số: Nhập đối tượng JSON xác định từng thông số (không bắt buộc) trên tài nguyên. Các thông số này được mô tả bên dưới.
Chọn Add Resource (Thêm tài nguyên). Bạn sẽ được chuyển hướng đến trang mô hình. Bạn có thể làm điều này ngay bây giờ xác định các phương thức trên tài nguyên.

Nếu muốn, bạn có thể thêm các tham số vào tài nguyên, chẳng hạn như mẫu, truy vấn và tiêu đề tham số. Tất cả tham số tài nguyên đều được kế thừa theo bất kỳ phương thức nào được xác định trên tài nguyên đó. Do đó, nếu bạn xác định một tham số truy vấn trên tài nguyên, thì tất cả phương thức được thêm vào tài nguyên đó phải hỗ trợ tham số truy vấn đó.

Ngoài ra, bạn có thể xác định các tham số của một phương thức. Ví dụ: phương thức POST có thể hỗ trợ các tham số truy vấn không được phương thức DELETE hỗ trợ. Do đó, hãy thêm bất kỳ thông số nào dành riêng cho một phương thức khi bạn xác định phương thức đó, như được mô tả dưới đây.

Hình ảnh sau đây hiển thị trang SmartDocs hiện có cho API phê duyệt hoặc thu hồi ứng dụng dành cho nhà phát triển Apigee, trong đó mỗi loại thông số được làm nổi bật:

Mỗi loại tham số do một đối tượng JSON xác định:

Loại	Đối tượng JSON	Ghi chú
Mẫu	{ "dataType": "chuỗi", "defaultValue": "", "description": "Tên tổ chức.", "tên": "org_name", "bắt buộc": đúng, "loại": "TEMPLATE" }	Các tham số mẫu luôn là bắt buộc, vì vậy, hãy đặt required (bắt buộc) thành true và bỏ giá trị thành defaultValue. Giá trị description xuất hiện trong cửa sổ bật lên khi người dùng di chuột qua URL trong trang SmartDocs.
Truy vấn	{ "dataType": "chuỗi", "defaultValue": "", "description": "Vị trí.", "tên": "có", "bắt buộc": đúng, "loại": "QUERY" }	Tham số truy vấn bắt buộc vẫn có thể chỉ định một defaultValue, nhưng thường không có. Đối với các tham số truy vấn không bắt buộc, hãy đặt required (bắt buộc) thành false (sai) và chỉ định giá trị thành defaultValue.
Tiêu đề	{ "dataType": "chuỗi", "defaultValue": "ứng dụng/json", "description": "Chỉ định là <code>application/json</code>.", "name": "Loại nội dung", "bắt buộc": đúng, "loại": "TIÊU ĐỀ" }	Hãy lưu ý cách bạn có thể sử dụng thẻ HTML trong phần mô tả.

Loại

Đối tượng JSON

Ghi chú

Mẫu

{
"dataType": "chuỗi",
"defaultValue": "",
"description": "Tên tổ chức.",
"tên": "org_name",
"bắt buộc": đúng,
"loại": "TEMPLATE"
}

Các tham số mẫu luôn là bắt buộc, vì vậy, hãy đặt required (bắt buộc) thành true và bỏ giá trị thành defaultValue.

Giá trị description xuất hiện trong cửa sổ bật lên khi người dùng di chuột qua URL trong trang SmartDocs.

Truy vấn

{
"dataType": "chuỗi",
"defaultValue": "",
"description": "Vị trí.",
"tên": "có",
"bắt buộc": đúng,
"loại": "QUERY"
}

Tham số truy vấn bắt buộc vẫn có thể chỉ định một defaultValue, nhưng thường không có.

Đối với các tham số truy vấn không bắt buộc, hãy đặt required (bắt buộc) thành false (sai) và chỉ định giá trị thành defaultValue.

Tiêu đề

{
"dataType": "chuỗi",
"defaultValue": "ứng dụng/json",
"description": "Chỉ định là <code>application/json</code>.",
"name": "Loại nội dung",
"bắt buộc": đúng,
"loại": "TIÊU ĐỀ"
}

Hãy lưu ý cách bạn có thể sử dụng thẻ HTML trong phần mô tả.

Tham số mẫu xác định một biến trong đường dẫn tài nguyên. Ví dụ: bạn xác định hai tham số mẫu trên tài nguyên. Lưu ý cách mỗi định nghĩa tham số trong mảng tham số được phân tách bằng dấu phẩy:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Sau đó, bạn có thể sử dụng các tham số mẫu trong định nghĩa đường dẫn tài nguyên, có trong "{}". Ví dụ: đặt đường dẫn đến:

/login/{org_name}/{developer_email}

Trong trang API SmartDocs, người dùng phải chỉnh sửa URL để chỉ định phần org_name và developer_email của URL trước khi họ có thể gửi yêu cầu.

Xác định một phương thức

Xác định một hoặc nhiều phương thức cho từng tài nguyên. Định nghĩa phương thức chỉ định một động từ HTTP có thể được gọi trên tài nguyên. Một tài nguyên có thể có một phương thức duy nhất được xác định trên nó, hoặc nhiều phương thức.

Trong quá trình xác định phương thức, hãy chỉ định mọi tham số mà phương thức sử dụng, bao gồm cả truy vấn và tham số tiêu đề. Xem mô tả ở trên để biết tài nguyên để biết thông tin về cách thêm thông số đối với một phương thức.

Hình ảnh sau đây cho thấy một trang SmartDocs hiện có cho API Create Developer của Apigee với mỗi phần của trang được làm nổi bật bằng giá trị tương ứng mà bạn đặt khi xác định phương thức:

Hình ảnh tiếp theo hiển thị cùng một trang nhưng với Mô tả của Nội dung yêu cầu được chọn:

Cách xác định một phương thức:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình mà bạn muốn cập nhật, trong phần Hoạt động, hãy chọn API Các bản sửa đổi để xem tất cả các bản sửa đổi của mô hình.
Chọn một bản sửa đổi để chỉnh sửa.
Trên trang sửa đổi, chọn Add method (Thêm phương pháp) từ trình đơn thả xuống cho một trong các tài nguyên.
Trên trang Phương thức chỉnh sửa, hãy nhập những thông tin sau:
- Tên hiển thị: Tên của API, cũng trở thành tiêu đề của Trang Drupal cho API.
- Mô tả: Mô tả API.
- Phương thức Động từ: Loại động từ HTTP.
- Lược đồ bảo mật: Chỉ định chế độ xác thực (nếu có) cho . Để biết thêm thông tin, hãy xem phần Định cấu hình phương thức xác thực SmartDocs .
- Loại nội dung: Loại nội dung của yêu cầu và phản hồi. Xem phần dưới đây về cách định cấu hình các phương pháp xác thực.
- Thông số: (Không bắt buộc) Bất kỳ tham số tiêu đề hoặc truy vấn nào cho phương thức. Hãy xem nội dung mô tả ở trên để biết cách thêm tham số vào tài nguyên để biết thêm thông tin.
- Tài liệu về nội dung yêu cầu: (Không bắt buộc) Mô tả nội dung yêu cầu. ĐĂNG và phương thức PUT lấy nội dung yêu cầu. Bạn có thể sử dụng vùng này để mô tả. Nếu bạn bỏ qua thuộc tính này thì đường liên kết Mô tả trong phần Nội dung yêu cầu bị bỏ qua từ trang SmartDocs đã tạo.
- Ví dụ về nội dung yêu cầu: (Không bắt buộc) Hiển thị ví dụ về nội dung yêu cầu, thường dưới dạng đối tượng JSON hoặc XML. Đối với động từ POST và PUT, phần Request body (Nội dung yêu cầu) Ví dụ được chuyển như một phần của mỗi yêu cầu. Người dùng trang SmartDocs chỉnh sửa nội dung này trước khi gửi yêu cầu tới API. Nếu bạn bỏ qua giá trị này, Đường liên kết Giá trị trong phần Nội dung yêu cầu bị loại bỏ khỏi trang SmartDocs đã tạo.
- Thẻ: Một loạt thẻ được liên kết với API. SmartDocs dùng thẻ để nhóm các API tương tự lại với nhau. Ví dụ: bạn có thể áp dụng thẻ "Thống kê" cho tất cả API về số liệu thống kê. Bạn có thể nhóm API từ nhiều tài nguyên trong một thẻ duy nhất. nếu chúng đều sử dụng cùng một thẻ.
Chọn Thêm phương thức. Bạn sẽ được chuyển hướng đến trang mô hình. Bạn có thể làm điều này ngay bây giờ hiển thị và xuất bản phương thức của bạn.

Kết xuất mô hình

Sau khi thêm các API vào một mô hình, bạn có thể kết xuất mô hình đó. Quá trình kết xuất sẽ chuyển đổi dữ liệu của mô hình nội dung mô tả về API vào các nút Drupal. Khi kết xuất xong, bạn sẽ có một Drupal nút cho mỗi API, trong đó mỗi nút Drupal tương ứng với một trang HTML.

Bạn có thể chọn kết xuất toàn bộ mô hình cùng một lúc hoặc chọn các API riêng lẻ để kết xuất hình ảnh.

Cách kết xuất mô hình:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
Đối với mô hình mà bạn muốn hiển thị, hãy chọn Bản sửa đổi API trong Thao tác.
Chọn bản sửa đổi bạn muốn kết xuất. Bạn chỉ có thể kết xuất các nút từ một bản xem lại duy nhất của mô hình.
Chọn phương thức kết xuất.
Chọn Nút hiển thị trong phần Cập nhật options.
Nhấp vào Cập nhật.
Một màn hình tải xuất hiện để xem tiến trình trên các nút đang được kết xuất.
Sau khi các nút được kết xuất, ID của nút Drupal cho mỗi API sẽ xuất hiện trong Cột Mối liên kết nút của mô hình. Nhấp vào đường liên kết trong Nút Liên kết để xem nút đã kết xuất.

Thay vì chọn Nút hiển thị,bạn có thể chọn Nút hiển thị và xuất bản các nút để kết xuất và xuất bản ngay lập tức các API dưới dạng nút Drupal.

Nút xuất bản

Người dùng cổng thông tin sẽ không nhìn thấy nút nào cho đến khi nút đó được xuất bản. Bạn có thể tuỳ ý chọn xuất bản các nút trong quá trình kết xuất. Nếu chọn không xuất bản các nút, thì bạn phải xuất bản chúng theo cách thủ công sau khi quá trình kết xuất hoàn tất.

Cách xuất bản một nút:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn xuất bản, hãy chọn Bản sửa đổi API trong Thao tác.
Chọn bản sửa đổi bạn muốn xuất bản. Bạn chỉ có thể xuất bản các nút từ một bản sửa đổi của mô hình.
Chọn phương thức xuất bản.
Chọn các nút trong bản sửa đổi để xuất bản.
Chọn Nút xuất bản từ phần Cập nhật options.
Nhấp vào Cập nhật.
Di chuyển đến nút bằng cách chọn mã nút trong phần Mối liên kết nút .

Theo mặc định, URL của Drupal đến nút API đã xuất bản có dạng: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Sử dụng quy trình sau đây để kiểm soát dạng thức của URL:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Cấu hình > Tìm kiếm và siêu dữ liệu > Bí danh URL > Mẫu trong trình đơn quản trị Drupal.
Trong phần Mẫu cho tất cả đường dẫn Phương pháp SmartDocs chỉ định cách bạn muốn tạo đường dẫn.
Chọn Lưu cấu hình.

Do lưu vào bộ nhớ đệm trên cổng thông tin, bạn có thể không thấy các trang mô hình của mình xuất hiện ngay lập tức sau khi xuất bản. Nếu cần, bạn có thể xoá bộ nhớ đệm HTML của SmartDocs theo cách thủ công bằng cách sử dụng quy trình sau:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Cấu hình > SmartDocs trong quản trị Drupal .
Nhấp vào Tạo lại bộ nhớ đệm mô hình SmartDocs.

Huỷ xuất bản nút

Bạn có thể hủy xuất bản nút đã xuất bản bất kỳ lúc nào. Việc huỷ xuất bản một nút sẽ ẩn nút đó người dùng cổng thông tin.

Cách huỷ xuất bản một nút:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn huỷ xuất bản, hãy chọn Bản sửa đổi API trong Thao tác.
Chọn bản sửa đổi mô hình của nút bạn muốn huỷ xuất bản.
Chọn các nút trong bản sửa đổi để huỷ xuất bản.
Chọn Nút Huỷ xuất bản trong phần Cập nhật options.
Nhấp vào Cập nhật.

Xem bản sửa đổi mô hình

Bạn tạo bản sửa đổi mới của mô hình bằng cách nhập tệp WADL mới hoặc Thông số kỹ thuật OpenAPI vào mô hình hiện có hoặc bằng cách tạo thủ công một bản sửa đổi mới. Sau khi tạo bản sửa đổi mới, bạn có thể kết xuất và xuất bản bản sửa đổi, thay thế các nút Drupal đã xuất bản.

Bạn có thể kết xuất và xuất bản các nút từ nhiều bản sửa đổi cùng một lúc. Tức là nếu bạn có năm bản sửa đổi của mô hình, bạn có thể xuất bản các nút từ bất kỳ hoặc tất cả bản sửa đổi. Tuy nhiên, việc phát hành một API trong một mô hình giống với nút đã xuất bản của một mô hình khác sẽ huỷ xuất bản của phiên bản API và thay thế bằng phiên bản của phiên bản được xuất bản gần đây nhất API.

Cách xem bản sửa đổi của mô hình:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn cập nhật, hãy chọn Bản sửa đổi API trong Thao tác.
Chọn bản sửa đổi mô hình mà bạn muốn xem.
Kết xuất và xuất bản các nút như mô tả ở trên.

Chỉnh sửa nút

Sau khi kết xuất một nút, bạn có thể chỉnh sửa nút đó bằng cách sử dụng trình chỉnh sửa Drupal. Ví dụ: bạn có thể chỉnh sửa động từ HTTP và nội dung mô tả về một API, hoặc thêm một truy vấn hay tham số tiêu đề mới vào API. Bạn có thể chỉnh sửa các nút được tạo từ tệp WADL hoặc Thông số kỹ thuật OpenAPI hoặc các nút đã tạo theo cách thủ công.

Bạn cũng có thể chỉnh sửa tệp WADL gốc hoặc OpenAPI Specification. Khi bạn xong việc với chỉnh sửa, nhập tệp WADL hoặc Thông số kỹ thuật OpenAPI vào mô hình dưới dạng bản sửa đổi mới, sau đó kết xuất và xuất bản các thay đổi như mô tả ở trên.

Cách chỉnh sửa một nút bằng trình chỉnh sửa Drupal:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Duyệt đến nút Drupal tương ứng với tài liệu về API mà bạn muốn chỉnh sửa.
Chọn Chỉnh sửa để sử dụng trình chỉnh sửa Drupal.
Sau khi bạn chỉnh sửa xong, hãy chọn Phương pháp cập nhật.

Hoặc, bạn có thể chỉnh sửa nút này từ mô hình SmartDocs:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn cập nhật, hãy chọn Bản sửa đổi API trong Thao tác.
Chọn bản sửa đổi mô hình mà bạn muốn xuất bản.
Chọn Phương pháp chỉnh sửa trong trình đơn thả xuống Hoạt động cho mà bạn muốn chỉnh sửa.

Cách xoá một nút:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn cập nhật, hãy chọn Bản sửa đổi API trong Thao tác.
Chọn bản sửa đổi mô hình mà bạn muốn xuất bản.
Chọn Xoá phương thức trong trình đơn thả xuống Thao tác cho phương thức.
Thận trọng: Việc xoá nút này cũng sẽ xoá API khỏi mô hình. Nếu bạn chỉ muốn huỷ xuất bản API để ẩn khỏi người dùng cổng thông tin nhưng không muốn xoá API đó khỏi mô hình, bạn nên huỷ xuất bản nút như mô tả ở trên.

Cổng thông tin có sẵn báo cáo hiển thị thông tin về bất kỳ nút nào được hiển thị bởi Mô hình SmartDocs không còn tham chiếu đến một phương thức hợp lệ của mô hình nữa. Truy cập vào báo cáo bằng chọn Báo cáo trong trình đơn Drupal, rồi chọn báo cáo có tên là trạng thái nút SmartDocs.

Xuất và nhập mô hình

SmartDocs cho phép bạn xuất mô hình hiện có sang tệp. Ví dụ: bạn có thể xác định và môi trường thử nghiệm. Sau đó, bạn thực hiện tất cả các chỉnh sửa SmartDocs của mình trong giai đoạn thử nghiệm môi trường. Khi đã sẵn sàng phát hành API, bạn xuất mô hình thử nghiệm và nhập mô hình đó vào mô hình sản xuất.

Việc nhập mô hình sẽ tạo ra một bản sửa đổi mới của mô hình. SmartTài liệu sẽ cố gắng khớp tài liệu hiện có Các API trong mô hình có API đã nhập. Nếu SmartDocs phát hiện kết quả trùng khớp, quá trình nhập sẽ cập nhật Drupal tương ứng với API hiện có. Nếu SmartDocs không phát hiện kết quả trùng khớp, thì lệnh nhập sẽ tạo một nút Drupal mới cho API.

Ví dụ: bạn có một API POST tương ứng với một nút Drupal có mã nhận dạng là 91. Sau đó bạn nhập mô hình và SmartDocs phát hiện kết quả trùng khớp của một API POST trong mô hình đã nhập với API hiện có API POST. Mọi nội dung cập nhật đối với POST API sẽ cập nhật nút Drupal 91. Nếu SmartDocs không phát hiện thấy so khớp, nó sẽ tạo một nút Drupal mới với một ID mới.

Drupal thực hiện so khớp bằng cách sử dụng các đặc điểm sau của API:

internalName: Tên mô hình nội bộ.
httpMethod: Phương thức HTTP của API, chẳng hạn như: GET, PUT, POST hoặc XOÁ.
resourcePath: Đường dẫn tài nguyên.
query params: Mọi tham số truy vấn mà API sử dụng.

Nếu cả 4 đặc điểm của một API đã nhập đều khớp với một API hiện có trong mô hình, thì SmartDocs cập nhật nút Drupal hiện có.

Mô hình đã xuất được biểu thị bằng một đối tượng JSON duy nhất với các mục nhập cho tài nguyên và . Điều đó có nghĩa là bạn có thể chỉnh sửa mô hình đã xuất để sửa đổi tài nguyên hoặc phương thức, sau đó nhập lại mô hình. Nếu bạn chỉnh sửa đối tượng JSON, đừng sửa đổi các trường sau:

revisionNumber
createdTime
modifiedTime
apiRevisionId
resourceId

Cách xuất một mô hình:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn xuất, hãy chọn Xuất trong Vận hành.
Chọn loại tệp xuất là SmartDocs JSON.
Nhấp vào Xuất.
Bạn được nhắc lưu tệp vào đĩa hoặc mở tệp trong trình chỉnh sửa.

Cách nhập mô hình:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn nhập, hãy chọn Nhập trong Vận hành.
Chọn SmartDocs JSON trong trình đơn thả xuống Chọn định dạng.
Chọn Tệp hoặc URL trong Loại tệp tải lên:
1. Nếu bạn chọn Tệp, hãy duyệt đến tệp JSON.
2. Nếu bạn chọn URL, hãy chỉ định URL của tệp JSON SmartDocs.
Nhấp vào Import (Nhập) để nhập vào mô hình.
Bạn được chuyển hướng đến trang thông tin của mô hình nơi bạn hiện có thể kết xuất mô hình. Lưu ý rằng việc nhập sẽ tạo ra một bản sửa đổi mới của mô hình.
Kết xuất và xuất bản các nút.

Chỉnh sửa mẫu SmartDocuments

Mẫu SmartDocs xác định cách các nút Drupal của bạn xuất hiện trên màn hình. Mỗi SmartTài liệu của bạn có thể sử dụng cùng một mẫu mặc định hoặc bạn có thể tuỳ chỉnh thủ công mẫu được sử dụng cho mô hình cá nhân.

Mẫu SmartDocs bao gồm một tệp mẫu được mã hoá dưới dạng tệp .hbr trên tay cầm, tệp CSS, và JavaScript. Khi sử dụng Thanh điều khiển, phần lớn nội dung được điều chỉnh bằng các thành phần được nhúng biểu thức tay điều khiển, chẳng hạn như &123;&123;body}}. Danh sách các lựa chọn hiện có Biểu thức trên thanh điều khiển được cung cấp trong phần nhận xét ở đầu tệp. Để biết thông tin về sử dụng Tay cầm để tuỳ chỉnh mẫu, hãy xem http://handlebarsjs.com.

Các phần sau đây mô tả cách tải tệp mẫu SmartDocuments tuỳ chỉnh lên để mọi người sử dụng mô hình mới hoặc cho thời điểm bạn nhập API mới vào mô hình hiện có, làm cách nào để khôi phục tệp mẫu SmartDocuments mặc định ban đầu và cách sửa đổi mẫu SmartDocs cho một mô hình cá nhân.

Tải tệp tuỳ chỉnh lên Tệp mẫu SmartDocs

Bạn có thể tải tệp mẫu SmartDocs tuỳ chỉnh lên, dưới dạng tệp .hbr trên tay cầm để sử dụng làm mẫu mặc định khi tạo mô hình mới hoặc nhập API mới vào mô hình hiện có.

Nếu bạn muốn sử dụng tệp mẫu SmartDocuments mặc định làm điểm bắt đầu khi tạo tệp mẫu SmartDocs tuỳ chỉnh của bạn, bạn có thể tải bản sao xuống từ: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Cách tải tệp mẫu SmartDocs tuỳ chỉnh lên:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Cấu hình > Smart Docs trong Drupal trình đơn quản trị.
Mở rộng phần Cài đặt nâng cao của trang.
Trong Tải lên mẫu phương pháp tuỳ chỉnh, hãy nhấp vào Chọn tệp rồi chuyển đến tệp .hbr trên tay cầm.
Nhấp vào Tải lên.
Nhấp vào Lưu cấu hình.

Khôi phục tệp mẫu SmartDocuments mặc định

Bạn có thể khôi phục tệp mẫu SmartDocs mặc định. Sau khi được khôi phục, SmartDocs mặc định tệp mẫu sẽ được sử dụng khi tạo mô hình mới hoặc nhập API mới vào mô hình.

Cách khôi phục tệp mẫu SmartDocs mặc định:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Cấu hình > Smart Docs trong Drupal trình đơn quản trị.
Mở rộng phần Cài đặt nâng cao của trang.
Trong Tải lên mẫu phương pháp tuỳ chỉnh, hãy nhấp vào Xoá bên cạnh tệp mẫu SmartDocs tuỳ chỉnh.
Nhấp vào Lưu cấu hình.

Đang sửa đổi mẫu SmartDocs cho một mẫu riêng lẻ

Bạn có thể sửa đổi mẫu được sử dụng cho từng mô hình.

Cách sửa đổi mẫu cho từng mô hình:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình bạn muốn chỉnh sửa, hãy chọn Cài đặt trong Vận hành.
Trong vùng Mẫu phương thức, hãy chỉnh sửa mẫu theo yêu cầu.
Nhấp vào Lưu mẫu.
Duyệt đến một nút Drupal. Bạn sẽ thấy các thay đổi đối với mẫu trên trang.

Định cấu hình Loại xác thực SmartDocs

Các API được xác định trong SmartDocs có thể mở, nghĩa là không có thông tin xác thực nào cần thiết để truy cập hoặc bảo mật. API bảo mật yêu cầu bạn truyền thông tin xác thực khi thực hiện lệnh gọi API.

Đối với API bảo mật, SmartDocs hỗ trợ các loại xác thực sau:

Xác thực cơ bản - Truyền thông tin xác thực cơ bản dưới dạng tên người dùng và mật khẩu. Nếu bạn không chỉ định sử dụng OAuth làm loại thông tin xác thực, API mặc định là sử dụng xác thực cơ bản.
OAuth 2.0 – Nhà cung cấp dịch vụ bên thứ ba xác thực thông tin thông tin xác thực, đảm bảo rằng người dùng được uỷ quyền vào API, sau đó cấp quyền truy cập mã thông báo. Khi bạn đưa ra yêu cầu SmartDocs cho một API được bảo vệ, SmartDocs sẽ tạo yêu cầu và gửi mã đến nhà cung cấp dịch vụ. Sau đó, nhà cung cấp dịch vụ sẽ xác thực mã thông báo và đảm bảo thông báo rằng mã này chưa hết hạn.
Mã thông báo tuỳ chỉnh – Truyền một giá trị mã thông báo dưới dạng tiêu đề hoặc tham số truy vấn cho mỗi mã của bạn.

Đối với mỗi loại xác thực, bạn tạo một sơ đồ bảo mật xác định đặc điểm của xác thực. Ví dụ: đối với xác thực mã thông báo tuỳ chỉnh, lược đồ bảo mật xác định cách truyền mã thông báo (tiêu đề, tham số truy vấn, tham số nội dung) và tên của mã thông báo.

Mỗi lược đồ bảo mật được liên kết với một bản sửa đổi cụ thể của một mô hình. Do đó, nếu bạn tạo bản sửa đổi mới của mô hình, bạn phải xác định lại lược đồ bảo mật cho bản sửa đổi đó

Trong tệp WADL, bạn sẽ chỉ định liệu API có yêu cầu xác thực hay không bằng cách sử dụng thẻ Apigee <apigee:authentication>, như được hiển thị bên dưới:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

Nếu API đang mở, hãy đặt thuộc tính required thành false.

Lưu ý rằng bạn không thể chỉ định loại xác thực trong tệp WADL. Bạn làm điều đó bằng cách chỉnh sửa nút trong Drupal. Để biết thêm thông tin về tệp WADL, hãy xem phần WADL Tệp đối chiếu.

Trên trang API trong Drupal, SmartDocuments thêm nút sau để cho phép người dùng chỉ định thông tin xác thực cơ bản:

Nếu bạn chỉnh sửa nút này để đặt loại xác thực thành OAuth, thì SmartDocs sẽ thêm phương thức nút sau vào trang:

Đối với mã thông báo tuỳ chỉnh, SmartDocs thêm:

Đang định cấu hình xác thực cơ bản

Nếu sử dụng phương thức xác thực cơ bản với API, thì bạn chỉ phải chỉ định thẻ <apigee:authentication> trong WADL mà bạn sử dụng để tạo mô hình.

Cách áp dụng phương thức xác thực cơ bản cho các phương thức được tạo từ một nguồn không phải tệp WADL:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình mong muốn, chọn Bản sửa đổi API trong Thao tác.
Đối với bản sửa đổi mô hình bạn muốn chỉnh sửa, hãy chọn Bảo mật Cài đặt trong phần Hoạt động.
Chọn Add Security Scheme (Thêm lược đồ bảo mật).
Chỉ định tên của lược đồ bảo mật.
Chọn Cơ bản làm Loại.
Chọn Gửi.
Đối với mỗi phương thức trong mô hình, hãy chỉnh sửa phương thức đó để đặt Lược đồ bảo mật cho lược đồ cơ bản.
1. Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
2. Đối với mô hình mong muốn, chọn Bản sửa đổi API trong Thao tác.
3. Đối với bản sửa đổi mô hình bạn muốn chỉnh sửa, hãy chọn Bản sửa đổi Thông tin chi tiết trong phần Hoạt động.
4. Chọn Phương thức chỉnh sửa cho API mà bạn muốn chỉnh sửa.
5. Chọn Security Scheme (Giao thức bảo mật) cho API.
6. Lưu API.

Đang định cấu hình Xác thực OAuth 2.0

Bạn có thể định cấu hình một mô hình để sử dụng OAuth 2.0 trong SmartDocs, thay vì mặc định là cơ bản xác thực. Bạn định cấu hình OAuth ở hai vị trí:

Tạo lược đồ bảo mật cho mỗi bản sửa đổi mô hình trong phần Bảo mật Chế độ cài đặt của bản sửa đổi.
Chỉ định ID ứng dụng khách và Mật khẩu ứng dụng khách cho tất cả các bản sửa đổi của mô hình trong Chế độ cài đặt cho mô hình.

Cách bật OAuth:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Vận hành.
Đối với bản sửa đổi mô hình bạn muốn chỉnh sửa, hãy chọn Cài đặt bảo mật trong Vận hành.
Chọn Add Security Scheme (Thêm lược đồ bảo mật).
Chỉ định tên của lược đồ bảo mật.
Chọn OAuth 2.0 làm Type (Loại).
Đặt Loại tài trợ.
Nhập các giá trị vào trường URL uỷ quyền. Việc uỷ quyền URL được dùng để lấy mã truy cập.
Đặt Động từ uỷ quyền thành GET hoặc POST.
Nhập URL mã thông báo truy cập. URL mã truy cập là URL dùng để trao đổi mã thông báo yêu cầu lấy mã truy cập.
Nhập tên tham số Mã truy cập.
Sử dụng phương thức In để chỉ định cách chuyển mã thông báo: Header (Tiêu đề), Cụm từ tìm kiếm hoặc Nội dung.
Đặt Phạm vi OAuth.
Chọn Gửi.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình, hãy chọn Cài đặt trong phần Hoạt động trình đơn thả xuống.
Nhập các giá trị trong trường Client ID và Client Bí mật.
Chọn Lưu chế độ xác thực mẫu.
Đối với mỗi phương thức trong mô hình, hãy chỉnh sửa phương thức đó để đặt Lược đồ bảo mật vào lược đồ bảo mật OAuth của bạn.
1. Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
2. Đối với mô hình mong muốn, chọn Bản sửa đổi API trong Thao tác.
3. Đối với bản sửa đổi mô hình bạn muốn chỉnh sửa, hãy chọn Bản sửa đổi Thông tin chi tiết trong phần Hoạt động.
4. Chọn Phương thức chỉnh sửa cho API mà bạn muốn chỉnh sửa.
5. Chọn Security Scheme (Giao thức bảo mật) cho API.
6. Lưu API.

Định cấu hình phương thức xác thực mã thông báo tuỳ chỉnh

Bạn có thể định cấu hình một mô hình để sử dụng xác thực mã thông báo tuỳ chỉnh.

Cách bật mã thông báo tuỳ chỉnh:

Đăng nhập vào cổng thông tin của bạn với tư cách là người dùng có đặc quyền của quản trị viên hoặc quyền tạo nội dung.
Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
Đối với mô hình mong muốn, chọn Bản sửa đổi API trong Thao tác.
Đối với bản sửa đổi mô hình bạn muốn chỉnh sửa, hãy chọn Bảo mật Cài đặt trong phần Hoạt động.
Chọn Add Security Scheme (Thêm lược đồ bảo mật).
Chỉ định tên của lược đồ bảo mật.
Chọn Apikey làm Loại.
Đặt Tên tham số chứa mã thông báo.
Sử dụng hàm In để chỉ định cách truyền hàm mã thông báo: Tiêu đề, Truy vấn, hoặc Nội dung.
Chọn Gửi.
Đối với mỗi phương thức trong mô hình, hãy chỉnh sửa phương thức đó để đặt Lược đồ bảo mật cho lược đồ mã thông báo của bạn.
1. Chọn Nội dung > SmartTài liệu trong trình đơn quản trị Drupal.
2. Đối với mô hình mong muốn, chọn Bản sửa đổi API trong Thao tác.
3. Đối với bản sửa đổi mô hình bạn muốn chỉnh sửa, hãy chọn Bản sửa đổi Thông tin chi tiết trong phần Hoạt động.
4. Chọn Phương thức chỉnh sửa cho API mà bạn muốn chỉnh sửa.
5. Chọn Security Scheme (Giao thức bảo mật) cho API.
6. Lưu API.

Xoá người mẫu

Khi bạn xoá một mô hình (Nội dung > SmartDocs, Xoá trong trường Hoạt động trong Drupal), mô hình sẽ bị xoá khỏi tổ chức Edge. Điều đó có nghĩa là nếu các cổng khác đang tham chiếu đến mô hình đó, thì mô hình này không còn hoạt động nữa. Để biết thêm thông tin, hãy xem bài viết Giới thiệu về các mô hình và mẫu SmartDoc.