Chuyển tới nội dung chính

API Document Management and API Test

Tổng Quan​

Quản lý tài liệu API một cách chính xác là rất quan trọng cho việc đào tạo nhà phát triển, kiểm tra và tích hợp. APIM cho phép bạn đính kèm các thông số OpenAPI hoặc định nghĩa tài liệu một cách thủ công, sau đó kiểm tra các API ngay lập tức trong giao diện. Hướng dẫn này cho thấy cách tải lên/chỉnh sửa tài liệu và chạy các bài kiểm tra cho một API đã được triển khai bằng cách sử dụng các cấu hình mẫu.

Điều Kiện Tiên Quyết​

Bạn sẽ cần:

  • Một phiên bản API đã được triển khai (ví dụ: user-service-api v1.0)
  • Quyền truy cập vào APIM Console với quyền Editor hoặc Administrator
  • Tệp thông số OpenAPI hoặc chi tiết định nghĩa API nếu viết thủ công

Hướng Dẫn Từng Bước​

Bước 1. Mở Trang Chi Tiết Phiên Bản API​

  • Đi đến Quản lý API
  • Chọn user-service-api
  • Chọn phiên bản v1.0

Bước 2. Tải Lên hoặc Chỉnh Sửa Tài Liệu API​

Bạn có hai tùy chọn:

Tùy chọn A: Tải lên OpenAPI (YAML/JSON)

  • Nhấp vào Nhập
  • Chọn và tải lên tệp OpenAPI 3.0 của bạn (ví dụ: user-service-v1.yaml)
  • Hệ thống sẽ phân tích và cập nhật tất cả các điểm cuối và mô tả

Tùy chọn B: Định Nghĩa API Thủ Công

Nếu không có tệp OpenAPI:

  • Nhấp vào Chỉnh sửa dưới tab Tài liệu
  • Thêm chi tiết thủ công: | Trường | Ví dụ | | --- | --- | | Tóm tắt | Điểm cuối đăng nhập người dùng | | Phương thức | POST | | Đường dẫn | /login | | Thân yêu cầu | JSON với tên người dùng, mật khẩu | | Phản hồi | 200 OK + thân JSON |

Nhấp vào Lưu khi hoàn tất.

Bước 3. Kiểm Tra API Sử Dụng Trình Kiểm Tra Tích Hợp Sẵn​

Đi đến tab Kiểm tra trong trang chi tiết phiên bản API:

TrườngGiá trị
Phương thức mục tiêuPOST
Đường dẫn/v1/login
Tiêu đềContent-Type: application/json

Ví dụ về thân yêu cầu:

{
"username": "jane.doe",
"password": "test1234"
}

Nhấp vào Gửi Yêu Cầu

Bước 4. Xem Xét Kết Quả Kiểm Tra​

Phản hồi mong đợi:

{
"userId": "12345",
"token": "eyJhbGciOi..."
}

Bảng điều khiển sẽ hiển thị:

  • Mã trạng thái HTTP (ví dụ: 200 OK)
  • Thời gian thực hiện
  • Nội dung yêu cầu & phản hồi

Các Vấn Đề Thường Gặp & Khắc Phục​

Vấn đềNguyên nhânGiải pháp
Tệp OpenAPI không hợp lệLỗi cú pháp hoặc các trường không được hỗ trợXác thực bằng Swagger Editor
Không có phản hồi trong bài kiểm traĐường dẫn sai hoặc thiếu backendKiểm tra lại đường dẫn Gateway và tình trạng backend
401 UnauthorizedThiếu khóa API hoặc chính sách xác thựcĐặt tiêu đề Authorization hoặc tạm thời vô hiệu hóa xác thực
415 Unsupported Media TypeThiếu hoặc sai Content-TypeSử dụng application/json cho các yêu cầu body

Các Thực Hành Tốt Nhất​

  • Luôn tải lên một đặc tả OpenAPI đã được xác thực để có tài liệu chính xác
  • Thêm các yêu cầu/phản hồi ví dụ cho mỗi điểm cuối
  • Sử dụng công cụ thử nghiệm tích hợp trước khi chia sẻ API với người tiêu dùng bên ngoài
  • Tài liệu phản hồi lỗi (4xx/5xx), không chỉ các trường hợp thành công
  • Giữ tài liệu API được phiên bản hóa theo vòng đời API