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

SmartDocs cho phép bạn ghi lại 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 khiến tài liệu API có khả năng tương tác đầy đủ. Tài liệu tương tác nghĩa là người dùng cổng thông tin có thể:

  • Đọc về 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 mà API trả về

Bằng cách tạo tài liệu có tính tương tác trên API, bạn giúp người dùng cổng thông tin dễ dàng tìm hiểu, kiểm tra 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 các Dịch vụ API bằng bất kỳ ứng dụng HTTP nào. Apigee sử dụng SmartDocs để tạo tài liệu có tính tương tác cho API quản lý Edge. Xem tài liệu về API đó tại đây.

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

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

Trên trang chủ cổng thông tin cho nhà phát triể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 ghi nhận trên cổng thông tin: Ví dụ về Hello World và Pet Store.

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

API mẫu cho Cửa hàng thú cưng được tạo từ bản minh hoạ cửa hàng thú cưng cổ điển.

Khám phá Hello World API:

  1. Nhấp vào Hello World API (API Hello World). Trang tóm tắt của Hello World API hiển thị:
  2. Nhấp vào Xem lời tự động viên sử dụng API. SmartDocs của tài nguyên này xuất hiện:
  3. Nhấp vào Gửi yêu cầu này.
  4. 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>
    
  5. Nhấp vào thẻ Request (Yêu cầu) để xem yêu cầu hoặc thẻ cURL để xem lệnh gọi cURL tương ứng.

Cách ghi lại API bằng SmartDocs

SmartDocs biểu thị API của bạn bằng cách sử dụng một model, 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, tại đó mỗi nút Drupal tương ứng với một trang tài liệu trên cổng thông tin.

Các bước chung mà bạn làm theo để sử dụng SmartDocs là:

  1. Định cấu hình mô-đun Drupal SmartDocs trên cổng thông tin.
  2. Tạo một mô hình SmartDocs.
  3. Thêm API vào mô hình từ tệp WADL, thông số kỹ thuật OpenAPI (trước đây là Swagger) hoặc theo cách thủ công.
  4. Hiển thị 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ả yêu cầu POST và PUT, thì SmartDocs tạo một nút Drupal riêng cho yêu cầu POST và PUT.
  5. Phát hành các nút Drupal. Sau khi xuất bản, người dùng cổng thông tin của bạn có thể xem và tương tác với API của bạn.
  6. Chỉnh sửa nút Drupal, trước hoặc sau khi bạn xuất bản nút. 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 lại tệp đó vào mô hình dưới dạng bản sửa đổi mới, sau đó hiển thị và xuất bản các thay đổi.
  7. Bật TLS. Vì SmartDocs có thể gửi thông tin xác thực đến phần phụ trợ của bạn trong quá trình đưa ra yêu cầu đối với API, bạn nên bật TLS trên cổng thông tin của mình để đảm bảo rằng các thông tin đăng nhập đó được an toàn. Trong môi trường phát hành chính thức và kiểm thử cổng thông tin, Apigee cung cấp chứng chỉ TLS cần thiết để thực hiện các yêu cầu https://. Tuy nhiên, trước khi phát hành chính thức cổng thông tin của mình, 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 phần 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 của mình, mô hình đó sẽ thực sự được lưu trữ trong tổ chức của bạn ở 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à xác định cấu trúc của API. Mặt khác, cổng của bạn sẽ hiển thị mô hình ở 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 thông tin sẽ tự động được đẩ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

Giả sử bạn có nhiều cổng trong tổ chức (ví dụ: cổng phát triển, giai đoạn và sản xuất). Trong Pantheon, bạn 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ổng thông tin có vẻ như chứa mô hình riêng, nhưng tất cả các thực thể đó đều thực sự tham chiếu đến mô hình nguồn. Nếu bạn chỉnh sửa API trong nhà phát triển, thì 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à sẽ không còn xuất hiện trong phiên bản chính thức nữa.

Mẫu sẽ kiểm soát giao diện của SmartDocs và các mẫu đó (được quản lý bằng Tay cầm và tệp CSS) được lưu trữ với từng thực thể cổng thông tin. Vì vậy, trên lý thuyết, mỗi cổng có thể sử dụng một mẫu riêng biệt cho mỗi mô hình. Tuy nhiên, một trong những điểm thuận tiện của khung kết xuất là hệ thống sẽ tự động áp dụng một mẫu mặc định (mẫu mặc định của Apigee hoặc mẫu mà bạn cung cấp) 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 thông tin. Mũi tên màu xanh lục cho biết tính năng đồng bộ hoá tự động.

Lệnh cURL sau đây liệt kê tất 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 làm theo quy trình sau để định cấu hình mô-đun SmartDocs.

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

  1. Đă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 tạo nội dung.
  2. Chọn 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.
  3. Bật mô-đun SmartDocs.
  4. Lưu cấu hình.
  5. Chọn Modules (Mô-đun) trong trình đơn quản trị của Drupal.
  6. Chọn SmartDocs -> Permissions và đảm bảo rằng bạn đã bật chế độ "Thực hiện tác vụ quản trị cho mô-đun SmartDocs" cho vai trò "Quản trị viên".
  7. Chọn Cấu hình > Cổng nhà phát triển trong trình đơn quản trị Drupal.
  8. Đặt Thời gian chờ kết nốiThời gian chờ yêu cầu thành 16 giây.
  9. Lưu cấu hình.
  10. Định cấu hình các 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 > Cài đặt trên trình đơn Drupal.
    2. Đặt Độ dài bí danh tối đaĐộ dài thành phần tối đa thành 255.
    3. Mở rộng phần Dấu câu.
    4. Đối với các chế độ cài đặt Dấu ngoặc nhọn trái ({)Dấu ngoặc nhọn phải (}), hãy 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.
  11. Nếu cổng thông tin dành cho nhà phát triển của bạn sẽ hiển thị với người dùng trong mạng nội bộ mà không có quyền truy cập Internet hoặc nếu một số API của bạn nằm trên mạng riêng, hãy định cấu hình URL proxy API SmartDocs như sau:
    1. Chọn Cấu hình > Tài liệu thông minh trong trình đơn 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 cùng dòng sẽ 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 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ề đại diện 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ợ nhiều API hoặc nhóm tất cả API vào một mô hình duy nhất.

Mỗi mô hình sẽ 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ư: lấy, đặt, đăng 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 của nút Drupal đã tạo cho yêu cầu GET tới tài nguyên có tên "/books" sẽ là:

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

Để tạo một 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 của bạn dưới dạng nguồn cho cấu trúc API. Để biết thêm thông tin, hãy xem phần Giới thiệu về mô hình và mẫu SmartDoc.

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Chọn Mô hình mới ở đầu trang.
  4. Nhập các trường sau:
    • Tên: Tên mô hình sẽ được hiển thị trên trang web.
    • Internal name (Tên nội bộ): Khi bạn nhập Tên, tên nội bộ sẽ hiển thị. Tên nội bộ cho mô hình phải là duy nhất trong số tất cả mô hình. Tên nội bộ chỉ được chứa chữ cái viết 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.
    • Mô tả: Nội dung mô tả về mô hình.
  5. 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 Hoạt động để:

  • Nhập tệp WADL mô tả API của bạn hoặc chỉ định URL của Thông số kỹ thuật OpenAPI 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 của mô hình, bao gồm các biểu định kiểu mà mô hình sử dụng.
  • Xuất mô hình sang 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 của SmartDocs vào một mô hình. Trước tiên, tệp này thường được tạo bằng cách xuất mộ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, hãy xem phần "Xuất và nhập 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 Thông số kỹ thuật OpenAPI.

Nhập WADL

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị của Drupal.
  3. Chọn mô hình mà bạn muốn cập nhật.
  4. Trong Operations (Hoạt động), hãy chọn Import (Nhập).
  5. Chọn WADL trong trình đơn thả xuống Choose Format (Chọn định dạng) trên trang nhập SmartDocs.
  6. Chọn File hoặc URL trong trình đơn thả xuống Upload Type (Loại tải lên).
    1. Nếu bạn chọn File (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.
  7. Nhấp vào Import (Nhập) để nhập vào mô hình. Bây giờ, bạn có thể kết xuất mô hình.
  8. Bạn sẽ được chuyển hướng đến trang thông tin của mô hình. Tại đây, bạn có thể kết xuất mô hình.

Nhập thông số kỹ thuật OpenAPI

Sau khi tạo mô hình thành công, bạn có thể nhập Thông số kỹ thuật của OpenAPI (trước đây là Swagger). 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ả API. Mỗi lần nhập một Thông số kỹ thuật OpenAPI, bạn sẽ tự động tạo một 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:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Chọn mô hình mà bạn muốn cập nhật.
  4. Trong Operations (Hoạt động), hãy chọn Import (Nhập).
  5. Chọn Swagger JSON hoặc Swagger YAML trong trình đơn thả xuống Choose Format (Chọn định dạng) trên trang nhập SmartDocs.
  6. Chọn File hoặc URL trong trình đơn thả xuống Upload Type (Loại 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 Specification (Thông số kỹ thuật OpenAPI).
    2. Nếu bạn chọn URL, hãy chỉ định URL của OpenAPI Specification.
  7. Nhấp vào Import (Nhập) để nhập vào mô hình.
  8. Bạn sẽ được chuyển hướng đến trang thông tin của mô hình. Tại đây, bạn có thể kết xuất mô hình.

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

Nếu không có tệp WADL hoặc Thông số kỹ thuật OpenAPI đại diện cho API của mình, bạn có thể thêm API vào mô hình theo cách thủ công. Ngoài ra, nếu sử dụng tệp WADL hoặc Thông số kỹ thuật OpenAPI để tạo mô hình, bạn có thể sử dụng quy trình này để chỉnh sửa các 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:

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

    Khi tạo bản sửa đổi, bạn sẽ chỉ định một đường dẫn cơ sở duy nhất cho tất cả API trong mô hình, nghĩa là tất cả API trong mô hình đều có cùng một đường dẫn cơ sở. Ví dụ: Hãy chỉ định đường dẫn cơ sở là:

    https://myCompany.com/v1

    Khi bạn thêm tài nguyên vào mô hình, các tài nguyên đó sẽ mở rộng đường dẫn cơ sở.
  2. 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 là "/login", thì URL đầy đủ của tài nguyên sẽ là:

    https://myCompany.com/v1/login
  3. Xác định một hoặc nhiều phương thức cho mỗi tài nguyên. Một phương thức sẽ chỉ định động từ HTTP có thể được gọi trên một tài nguyên. Ví dụ: đối với tài nguyên "/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 hai phương thức cho tài nguyên, một phương thức cho yêu cầu POST và một phương thức cho lệnh DELETE.

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

Theo quy 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 tài nguyên SmartDocs khác nhau cho mỗi tài nguyên duy nhất trong API của bạn.
  • Xác định một phương thức SmartDocs khác cho mỗi động từ HTTP mà một tài nguyên hỗ trợ.

Tạo bản xem lạ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 này đã 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 mới và chưa có bản sửa đổi nào, hãy tạo một bản sửa đổi mới.

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình bạn muốn cập nhật, hãy chọn Thêm Sửa đổi trong Hoạt động.
  4. 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 khi bản sửa đổi xuất hiện trên 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. Một mô hình 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 chỉ báo phiên bản vào URL cơ sở. Đối với phiên bản sửa đổi mô hình đầu tiên, URL cơ sở là:
      https://myCompany.com/v1
      Trong lần sửa đổi tiếp theo, URL cơ sở có thể là:
      https://myCompany.com/v2
  5. 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. Bây giờ, bạn có thể xác định tài nguyên trên mô hình.

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

Tài nguyên sẽ chỉ định URL đầy đủ của API. Khi xác định tài nguyên, bạn sẽ chỉ định đường dẫn tài nguyên. Đường dẫ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.

Cách xác định tài nguyên:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình bạn muốn cập nhật, trong Hoạt động, hãy chọn Bản sửa đổi API để xem tất cả các bản sửa đổi của một mô hình.
  4. Chọn một bản sửa đổi để chỉnh sửa.
  5. Trên trang sửa đổi, chọn Thêm tài nguyên từ trình đơn thả xuống.
  6. Trên trang Thêm tài nguyên, hãy nhập 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.
    • Mô tả: Mô tả về tài nguyên.
    • Tham số: Nhập đối tượng JSON (không bắt buộc) xác định từng tham số trên tài nguyên. Các thông số này được mô tả dưới đây.
  7. Chọn Add Resource (Thêm tài nguyên). Bạn sẽ được chuyển hướng đến trang mô hình. Bây giờ, bạn có thể xác định các phương thức trên tài nguyên.

Bạn có thể tuỳ ý thêm các tham số vào tài nguyên, chẳng hạn như các tham số mẫu, truy vấn và tiêu đề. Tất cả tham số tài nguyên đều được mọi phương thức xác định trên tài nguyên đó kế thừa. 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 đã thêm vào tài nguyên đó đều phải hỗ trợ tham số truy vấn đó.

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

Hình ảnh sau đây cho thấy một 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 của Apigee, trong đó từng loại tham số được làm nổi bật:

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

Loại

Đối tượng JSON

Ghi chú

Mẫu

{
"dataType": "string",
"defaultValue": "",
"description": "Tên tổ chức.",
"name": "org_name",
"required": đúng,
"type": "TEMPLATE"
}

Các tham số mẫu luôn là bắt buộc, vì vậy, hãy đặt required thành true và bỏ qua 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": "string",
"defaultValue": "",
"description": "Vị trí.",
"name": "w",
"required": true,
"type": "QUERY"
}

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

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

Đầu trang

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Chỉ định là <code>application/json</code>.",
"name": "Content-Type",
"required": true,
"type": "Header"
}

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 2 tham số mẫu trên tài nguyên. Hãy lưu ý cách phân tách từng định nghĩa tham số trong mảng tham số 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 phần định nghĩa Đường dẫn tài nguyên, có trong "{}". Ví dụ: đặt đường dẫn thành:

/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_namedeveloper_email của URL thì mới 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 mỗi 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ỗi tài nguyên có thể được xác định một 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ả tham số truy vấn và tiêu đề. Hãy xem nội dung mô tả ở trên để tham khảo tài nguyên nhằm biết thêm thông tin về cách thêm tham số vào 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, trong đó từng vùng trên 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 cho thấy cùng một trang nhưng đã chọn Nội dung mô tả của nội dung yêu cầu:

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình bạn muốn cập nhật, trong Hoạt động, hãy chọn Bản sửa đổi API để xem tất cả các bản sửa đổi của một mô hình.
  4. Chọn một bản sửa đổi để chỉnh sửa.
  5. Trên trang sửa đổi, hãy chọn Add Method (Thêm phương thức) trong trình đơn thả xuống cho một trong các tài nguyên.
  6. Trên trang Phương thức chỉnh sửa, hãy nhập 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 này.
    • 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 phương thức đó. Để biết thêm thông tin, hãy xem phần Định cấu hình loại 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 bên dưới về cách định cấu hình các phương thức xác thực.
    • Tham số: (Không bắt buộc) Bất kỳ tham số truy vấn hoặc tiêu đề nào cho phương thức. Để biết thêm thông tin, hãy xem nội dung mô tả ở trên để biết cách thêm tham số vào tài nguyên.
    • 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. Phương thức POST và PUT sẽ lấy nội dung yêu cầu. Bạn có thể sử dụng phần này để mô tả. Nếu bạn bỏ qua giá trị này, thì đường liên kết Mô tả trong phần Nội dung yêu cầu sẽ bị bỏ qua trên trang SmartDocs được tạo.
    • Ví dụ về nội dung yêu cầu: (Không bắt buộc) Cho thấy ví dụ về nội dung yêu cầu, thường ở dạng đối tượng JSON hoặc XML. Đối với động từ POST và PUT, Ví dụ về nội dung yêu cầu được truyền như một phần của mỗi yêu cầu. Người dùng trang SmartDocs chỉnh sửa ví dụ này trước khi họ 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 Nội dung yêu cầu sẽ bị bỏ qua trên trang SmartDocs được tạo.
    • Thẻ: Một dãy các thẻ được liên kết với API. SmartDocs sử dụng thẻ để nhóm các API tương tự với nhau. Ví dụ: bạn có thể áp dụng thẻ "Thống kê" cho tất cả API về thống kê. Bạn có thể nhóm các API từ nhiều tài nguyên vào một thẻ duy nhất nếu tất cả các API đó đều sử dụng cùng một thẻ.
  7. Chọn Thêm phương thức. Bạn sẽ được chuyển hướng đến trang mô hình. Bây giờ, bạn có thể kết xuất và phát hành phương thức.

Kết xuất mô hình

Sau khi thêm API vào một mô hình, bạn có thể kết xuất mô hình đó. Hoạt động kết xuất sẽ chuyển đổi nội dung mô tả về API của mô hình thành các nút Drupal. Khi quá trình hiển thị hoàn tất, bạn sẽ có một nút Drupal duy nhấ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 từng API riêng lẻ để kết xuất.

Cách hiển thị một mô hình:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình mà bạn muốn kết xuất, hãy chọn Bản sửa đổi API trong phần Hoạt động.
  4. Chọn bản sửa đổi mà bạn muốn hiển thị. Bạn chỉ có thể hiển thị các nút từ một bản sửa đổi của mô hình.
  5. Chọn các phương thức kết xuất.
  6. Chọn Render Nodes (Nút kết xuất) trong trình đơn thả xuống Update (Cập nhật) các tuỳ chọn.
  7. Nhấp vào Cập nhật.
  8. 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, mã của nút Drupal cho mỗi API sẽ xuất hiện trong cột Liên kết nút của mô hình. Nhấp vào đường liên kết trong cột Liên kết nút để xem nút đã kết xuất.

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

Xuất bản nút

Người dùng cổng thông tin sẽ không thấy một nút 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 không muốn xuất bản các nút, bạn sẽ phải phát hành các nút 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 nút:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đố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 phần Hoạt động.
  4. 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.
  5. Chọn các phương thức để xuất bản.
  6. Chọn các nút trong bản sửa đổi để xuất bản.
  7. Chọn Publish Nodes (Xuất bản nút) trong trình đơn thả xuống Update (Cập nhật) các tuỳ chọn.
  8. Nhấp vào Cập nhật.
  9. Di chuyển đến nút bằng cách chọn mã nhận dạng nút trong cột Mối liên kết với nút.

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

  1. Đă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 tạo nội dung.
  2. 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.
  3. Trong phần Mẫu cho tất cả đường dẫn phương thức SmartDocs chỉ định cách bạn muốn tạo đường dẫn.
  4. Chọn Lưu cấu hình.

Do việc lưu vào bộ nhớ đệm trên cổng thông tin nên bạn có thể không thấy các trang mô hình của mình xuất hiện ngay 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 làm theo quy trình sau:

  1. Đă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 tạo nội dung.
  2. Chọn Cấu hình > SmartDocs trong trình đơn quản trị Drupal.
  3. Nhấp vào Tạo lại bộ nhớ đệm của mô hình SmartDocs.

Huỷ xuất bản nút

Bạn có thể huỷ xuất bản nút đã xuất bản bất cứ lúc nào. Việc huỷ xuất bản một nút sẽ khiến người dùng cổng thông tin không nhìn thấy nút đó.

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đố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 phần Hoạt động.
  4. Chọn bản sửa đổi mô hình của nút bạn muốn huỷ xuất bản.
  5. Chọn các nút trong bản sửa đổi để hủy xuất bản.
  6. Chọn nút Huỷ xuất bản trong trình đơn thả xuống Tuỳ chọn Cập nhật.
  7. Nhấp vào Cập nhật.

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

Bạn tạo một 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ột mô hình hiện có hoặc bằng cách tạo một bản sửa đổi mới theo cách thủ công. Sau khi tạo bản sửa đổi mới, bạn có thể hiển thị và phát hành bản sửa đổi để thay thế các nút Drupal hiện đã 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. Nghĩa là nếu có 5 bản sửa đổi của một mô hình, bạn có thể xuất bản các nút từ bất kỳ hoặc tất cả các bản sửa đổi. Tuy nhiên, việc phát hành API trong một mô hình giống với nút đã xuất bản trong một mô hình khác sẽ huỷ xuất bản phiên bản API cũ và thay thế bằng một phiên bản từ API được phát hành gần đây nhất.

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đố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 phần Hoạt động.
  4. Chọn bản sửa đổi của mô hình mà bạn muốn xem.
  5. 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 hiển thị 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 tham số truy vấn hay 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 hay các nút được 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 Thông số kỹ thuật OpenAPI. Khi bạn chỉnh sửa xong, hãy nhập lại tệp WADL hoặc OpenAPI Specification 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 như mô tả ở trên.

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

  1. Đă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 tạo nội dung.
  2. 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.
  3. Chọn Chỉnh sửa để sử dụng trình chỉnh sửa Drupal.
  4. Sau khi chỉnh sửa xong, hãy chọn Cập nhật phương pháp.

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đố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 phần Hoạt động.
  4. Chọn bản sửa đổi mô hình mà bạn muốn xuất bản.
  5. Chọn Edit method (Chỉnh sửa phương thức) trong trình đơn thả xuống Operations (Hoạt động) cho phương thức mà bạn muốn chỉnh sửa.

Cách xoá nút:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đố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 phần Hoạt động.
  4. Chọn bản sửa đổi mô hình mà bạn muốn xuất bản.
  5. Chọn Delete method (Xoá phương thức) trong trình đơn thả xuống Operations (Hoạt động) 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, thì bạn nên huỷ xuất bản nút theo mô tả ở trên.

Cổng thông tin có sẵn một báo cáo hiển thị thông tin về bất kỳ nút nào do mô hình SmartDocs kết xuất và không còn tham chiếu đến các 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 cách chọn Báo cáo trong trình đơn Drupal, sau đó 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 môi trường sản xuất và môi trường thử nghiệm. Sau đó, bạn thực hiện tất cả các nội dung chỉnh sửa trong SmartDocs của mình trong môi trường thử nghiệm. Khi đã sẵn sàng phát hành API, bạn sẽ xuất mô hình thử nghiệm và nhập vào mô hình sản xuất.

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

Ví dụ: bạn có một POST API tương ứng với nút Drupal có mã nhận dạng là 91. Sau đó, bạn sẽ nhập một 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 POST hiện có. Mọi cập nhật đối với API POST sau đó sẽ cập nhật nút Drupal 91. Nếu không phát hiện thấy kết quả trùng khớp, SmartDocs tạo một nút Drupal mới với một mã nhận dạng mới.

Drupal thực hiện việc so khớp bằng cách sử dụng các đặc điểm sau đây 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 DELETE.
  • resourcePath: Đường dẫn tài nguyên.
  • tham số truy vấn: Mọi tham số truy vấn mà API sử dụng.

Nếu cả bốn đặc điểm của một API đã nhập khớp với 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à phương thức. Đ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 rồi 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:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình mà bạn muốn xuất, hãy chọn Export (Xuất) trong phần Operations (Hoạt động).
  4. Chọn loại tệp xuất là SmartDocs JSON.
  5. Nhấp vào Xuất.
  6. 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ột mô hình:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình bạn muốn nhập, hãy chọn Import (Nhập) trong phần Operations (Hoạt động).
  4. Chọn SmartDocs JSON trong trình đơn thả xuống Choose Format (Chọn định dạng).
  5. Chọn File (Tệp) hoặc URL trong Loại tải lên:
    1. Nếu bạn chọn File (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 cho SmartDocs.
  6. Nhấp vào Import (Nhập) để nhập vào mô hình.
  7. Bạn sẽ được chuyển hướng đến trang thông tin của mô hình. Tại đây, bạ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.
  8. Kết xuất và xuất bản các nút.

Chỉnh sửa mẫu SmartDocs

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 mô hình SmartDocs có thể sử dụng cùng một mẫu mặc định hoặc bạn có thể tuỳ chỉnh mẫu được sử dụng theo cách thủ công cho một mô hình riêng lẻ.

Mẫu SmartDocs bao gồm một tệp mẫu được mã hóa dưới dạng tệp .hbr Thanh tay cầm, tệp CSS và tệp JavaScript. Với Tay cầm, phần lớn nội dung được điều hướng thay đổi bằng cách sử dụng biểu thức tay cầm được nhúng, chẳng hạn như &123;&123;body}}. Danh sách các biểu thức Thanh điều khiển hiện có sẽ được cung cấp trong một nhận xét ở đầu tệp. Để biết thông tin về cách sử dụng Tay điều khiển để 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 SmartDocs tuỳ chỉnh lên để sử dụng cho tất cả mô hình mới hoặc khi bạn nhập API mới vào mô hình hiện có, cách khôi phục tệp mẫu SmartDocs mặc định ban đầu và cách sửa đổi mẫu SmartDocs cho một mô hình riêng lẻ.

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

Bạn có thể tải một tệp mẫu SmartDocs tuỳ chỉnh lên dưới dạng tệp .hbr Thanh điều khiển để 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 muốn sử dụng tệp mẫu SmartDocs mặc định làm điểm xuất phát khi tạo tệp mẫu SmartDocs tùy chỉnh của mình, bạn có thể tải xuống bản sao từ: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

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

  1. Đă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 tạo nội dung.
  2. Chọn Cấu hình > SmartDocs trong trình đơn quản trị của Drupal.
  3. Mở rộng khu vực Cài đặt nâng cao của trang.
  4. Trong phần Tải mẫu phương thức tuỳ chỉnh lên, hãy nhấp vào Chọn tệp rồi chuyển đến tệp Tay cầm .hbr.
  5. Nhấp vào Tải lên.
  6. Nhấp vào Lưu cấu hình.

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

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

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

  1. Đă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 tạo nội dung.
  2. Chọn Cấu hình > SmartDocs trong trình đơn quản trị của Drupal.
  3. Mở rộng khu vực Cài đặt nâng cao của trang.
  4. Trong phần Tải mẫu phương thức tuỳ chỉnh lên, hãy nhấp vào Xoá bên cạnh tệp mẫu SmartDocs tuỳ chỉnh.
  5. Nhấp vào Lưu cấu hình.

Sửa đổi mẫu SmartDocs cho từng mô hình

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

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > SmartDocs trong trình đơn quản trị Drupal.
  3. Đối với mô hình bạn muốn chỉnh sửa, hãy chọn Settings (Cài đặt) trong phần Operation (Hoạt động).
  4. Trong vùng Mẫu phương thức, chỉnh sửa mẫu theo yêu cầu.
  5. Nhấp vào Lưu mẫu.
  6. Duyệt đến một nút Drupal. Bạn sẽ thấy các thay đổi về mẫu trên trang này.

Đị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ần có thông tin xác thực để truy cập vào các API đó hoặc không cần 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 đến API.

Để có 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 cặp tên người dùng và mật khẩu. Nếu bạn không chỉ định dùng OAuth làm loại thông tin xác thực, thì theo mặc định, API sẽ sử dụng phương thức 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 đăng nhập của người dùng, đảm bảo rằng người dùng có quyền sử dụng API, sau đó cấp mã truy cập. Khi bạn gửi yêu cầu SmartDocs tới một API được bảo vệ, SmartDocs tạo yêu cầu và gửi yêu cầu đó đế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 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 vào từng yêu cầu.

Đối với mỗi loại xác thực, bạn sẽ tạo một sơ đồ bảo mật để xác định các đặc điểm của quy trình xác thực. Ví dụ: để xác thực mã thông báo tuỳ chỉnh, lược đồ bảo mật sẽ xác định cách chuyể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.

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 tạo một bản sửa đổi mới của một mô hình, bạn phải xác định lại các lược đồ bảo mật cho bản sửa đổi đó

Trong tệp WADL, bạn chỉ định xem một API có yêu cầu xác thực hay không bằng cách dùng thẻ Apigee <apigee:authentication> như sau:

<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 (bắt buộc) 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 có thể thực hiện việc này bằng cách chỉnh sửa nút này trong Drupal. Để biết thêm thông tin về tệp WADL, hãy xem Tài liệu tham khảo về WADL.

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

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

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

Định cấu hình phương thức 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 tệp WADL mà bạn 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:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
  3. Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Hoạt động.
  4. Đối với bản sửa đổi mô hình mà bạn muốn chỉnh sửa, hãy chọn Cài đặt bảo mật trong phần Hoạt động.
  5. Chọn Thêm lược đồ bảo mật.
  6. Chỉ định tên của lược đồ bảo mật.
  7. Chọn LoạiCơ bản.
  8. Chọn Gửi.
  9. Đối với mỗi phương thức trong mô hình, hãy chỉnh sửa để đặt Lược đồ bảo mật của phương thức đó thành lược đồ cơ bản.
    1. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
    2. Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Hoạt động.
    3. Đối với bản sửa đổi mô hình mà bạn muốn chỉnh sửa, hãy chọn Revision Details (Chi tiết bản sửa đổi) trong phần Operations (Hoạt động).
    4. Chọn Edit Method (Phương thức chỉnh sửa) cho API mà bạn muốn chỉnh sửa.
    5. Chọn Lược đồ bảo mật cho API.
    6. Lưu API.

Đị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ì phương thức xác thực cơ bản mặc định. Bạn định cấu hình OAuth ở hai vị trí:

  1. Tạo một lược đồ bảo mật cho mỗi bản sửa đổi của một mô hình trong phần Cài đặt bảo mật cho bản sửa đổi đó.
  2. Chỉ định Client-ID 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 phần Settings (Cài đặt) cho mô hình.

Cách bật OAuth:

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
  3. Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Hoạt động.
  4. Đối với bản sửa đổi mô hình mà bạn muốn chỉnh sửa, hãy chọn Cài đặt bảo mật trong phần Hoạt động.
  5. Chọn Thêm lược đồ bảo mật.
  6. Chỉ định tên của lược đồ bảo mật.
  7. Chọn OAuth 2.0 làm Loại.
  8. Đặt Loại cấp quyền.
  9. Nhập giá trị vào các trường URL uỷ quyền. URL uỷ quyền được dùng để lấy mã truy cập.
  10. Đặt Động từ ủy quyền thành GET hoặc POST.
  11. Nhập URL mã thông báo truy cập. URL mã thông báo truy cập là URL được dùng để trao đổi mã thông báo yêu cầu lấy mã thông báo truy cập.
  12. Nhập tên tham số Mã thông báo truy cập.
  13. Sử dụng tuỳ chọn In để chỉ định cách chuyển mã thông báo: Header, Query hoặc Body.
  14. Đặt Phạm vi OAuth.
  15. Chọn Gửi.
  16. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
  17. Đối với mô hình này, hãy chọn Settings (Cài đặt) trong trình đơn thả xuống Operation (Hoạt động).
  18. Nhập các giá trị trong trường Client-IDClient Secret.
  19. Chọn Lưu chế độ cài đặt xác thực mẫu.
  20. Đối với mỗi phương thức trong mô hình, hãy chỉnh sửa để đặt Lược đồ bảo mật của phương thức đó thành lược đồ bảo mật OAuth của bạn.
    1. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
    2. Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Hoạt động.
    3. Đối với bản sửa đổi mô hình mà bạn muốn chỉnh sửa, hãy chọn Revision Details (Chi tiết bản sửa đổi) trong phần Operations (Hoạt động).
    4. Chọn Edit Method (Phương thức chỉnh sửa) cho API mà bạn muốn chỉnh sửa.
    5. Chọn Lược đồ bảo mật cho API.
    6. Lưu API.

Định cấu hình 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 phương thức xác thực mã thông báo tuỳ chỉnh.

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

  1. Đă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 tạo nội dung.
  2. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
  3. Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Hoạt động.
  4. Đối với bản sửa đổi mô hình mà bạn muốn chỉnh sửa, hãy chọn Cài đặt bảo mật trong phần Hoạt động.
  5. Chọn Thêm lược đồ bảo mật.
  6. Chỉ định tên của lược đồ bảo mật.
  7. Chọn Apikey làm Loại.
  8. Đặt Tên Param chứa mã thông báo.
  9. Sử dụng In để chỉ định cách chuyển mã thông báo: Header, Query hoặc Body.
  10. Chọn Gửi.
  11. Đối với mỗi phương thức trong mô hình, hãy chỉnh sửa để đặt Lược đồ bảo mật của phương thức đó thành lược đồ mã thông báo của bạn.
    1. Chọn Nội dung > Tài liệu thông minh trong trình đơn quản trị Drupal.
    2. Đối với mô hình mong muốn, hãy chọn Bản sửa đổi API trong phần Hoạt động.
    3. Đối với bản sửa đổi mô hình mà bạn muốn chỉnh sửa, hãy chọn Revision Details (Chi tiết bản sửa đổi) trong phần Operations (Hoạt động).
    4. Chọn Edit Method (Phương thức chỉnh sửa) cho API mà bạn muốn chỉnh sửa.
    5. Chọn Lược đồ bảo mật cho API.
    6. Lưu API.

Xoá mô hình

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 của bạn trong Edge. Điều đó có nghĩa là nếu các cổng thông tin khác đang tham chiếu đến mô hình, thì mô hình này sẽ không còn nữa. Để biết thêm thông tin, hãy xem phần Giới thiệu về các mô hình và mẫu SmartDoc.