Theo mặc định, tài liệu của bạn có thể được truy cập trên domain [subdomain].apidog.io. Tuy nhiên, bạn có thể tùy chỉnh điều này bằng cách thiết lập một domain tùy chỉnh, nghĩa là người xem của bạn sẽ có thể truy cập tài liệu trên một domain phù hợp với tổ chức của bạn.Domain tùy chỉnh có thể được thiết lập bởi người dùng có quyền quản trị viên. Vui lòng làm theo các bước sau để thiết lập domain tùy chỉnh.Bắt đầu thiết lập domain tùy chỉnh#
Bạn có thể truy cập các tùy chọn thiết lập domain tùy chỉnh cho một dự án trong mô-đun Share của dự án. Chỉ cần nhấp vào menu Share Docs trong thanh bên, sau đó điều hướng đến trang cài đặt Publish trong menu phụ.Bạn sẽ thấy một phần có tiêu đề Custom Domain. Nhấp vào nút Edit để bắt đầu thiết lập domain tùy chỉnh.Có hai loại tùy chọn để thiết lập domain tùy chỉnh:1.
CNAME: Đây là tùy chọn được khuyến nghị. Đây là tùy chọn dễ thiết lập và duy trì nhất. Đây cũng là tùy chọn linh hoạt nhất, vì nó cho phép bạn thiết lập domain tùy chỉnh cho subdomain hoặc root domain.
2.
Reverse Proxy: Tùy chọn này nâng cao hơn và yêu cầu bạn sử dụng Content Delivery Network (CDN) hoặc tự thiết lập reverse proxy trên máy chủ của mình. Tùy chọn này được khuyến nghị cho người dùng quen thuộc với các công nghệ này.
Cấu hình CNAME#
Điều này chỉ áp dụng nếu bạn đã chọn tùy chọn CNAME ở bước trước.
2.
Chờ các thay đổi có hiệu lực
Cấu hình bản ghi CNAME#
Tên của các trường và nội dung thực tế cần nhập để cấu hình bản ghi có thể khác nhau giữa các bảng điều khiển DNS, nhưng chúng tôi đã đề cập đến các tùy chọn phổ biến nhất tại đây. Nếu bạn không chắc chắn, hãy xác minh với nhà cung cấp DNS của bạn.type là loại bản ghi DNS mà bạn muốn tạo. Ở đây, bạn cần chọn CNAME.
name hoặc DNS entry là nơi bạn nhập subdomain của mình. Bạn có thể cần nhập đầy đủ (ví dụ: docs.example.com) hoặc có thể chỉ cần nhập phần trước apex domain của bạn (ví dụ: docs). Nếu bạn không chắc nên sử dụng giá trị nào, hãy kiểm tra với nhà cung cấp DNS của bạn.
target hoặc value hoặc destination là nơi subdomain sẽ được trỏ tới. Bạn sẽ thấy giá trị này trong cài đặt Publish trong Apidog khi chọn tùy chọn DNS CNAME. Giá trị này sẽ trông giống như {projectId}.apidog.io. Bạn nên nhập đầy đủ giá trị này (ví dụ: 12345678.apidog.io).
Bạn cũng có thể thấy một trường có tên TTL, viết tắt của Time To Live. Đây là số giây mà bản ghi DNS có thể được lưu trong bộ nhớ đệm. Nếu bạn không chắc nên đặt giá trị nào, chúng tôi khuyên bạn nên chọn Auto hoặc giữ giá trị mặc định.
Bạn có đang sử dụng Cloudflare không?#
Nếu bạn đang cấu hình DNS trong bảng điều khiển của Cloudflare, vui lòng đảm bảo rằng proxy của Cloudflare (đám mây màu cam, cũng được gọi là "Proxy status" trong cài đặt domain của bạn) đã được tắt. Điều này vì hai lý do:Tùy chọn này che giấu mục tiêu DNS cho domain của bạn khỏi công chúng, ngăn Apidog thực hiện đúng các kiểm tra định kỳ trên domain tùy chỉnh của bạn.
Domain tùy chỉnh của bạn đã được hưởng lợi từ CDN.
Chờ các thay đổi có hiệu lực#
Câu trả lời ngắn gọn: bạn có thể cần chờ 10 minutes ~ 48 hours để các thay đổi DNS có hiệu lực trước khi chuyển sang bước tiếp theo.Bạn còn nhớ trường TTL (Time To Live) mà chúng tôi đã đề cập trước đó không? Bản ghi DNS được lưu trong bộ nhớ đệm trong một khoảng thời gian — điều này thường rất tốt cho hiệu năng, vì chúng thường không thay đổi thường xuyên. Khi chúng có thay đổi, sẽ có một khoảng thời gian (giá trị TTL) mà các máy chủ bộ nhớ đệm DNS cần để bộ nhớ đệm của chúng hết hạn trước khi kiểm tra bất kỳ thay đổi nào và hoạt động tương ứng.Trong hầu hết trường hợp, tốt nhất là chờ ít nhất 10 phút trước khi chuyển sang bước tiếp theo và cũng là bước cuối cùng. Đôi khi mọi thứ có thể cập nhật nhanh hơn một chút, hoặc có thể mất nhiều thời gian hơn. Hiếm khi quá trình này mất hơn 48 giờ.Bạn muốn kiểm tra tiến trình của quá trình này, được gọi là propagation, đang diễn ra như thế nào? Bạn có thể sử dụng công cụ tra cứu DNS, chẳng hạn như WhatsMyDNS. Nhập subdomain đầy đủ của bạn, chọn CNAME từ danh sách thả xuống và nhấn nút Search. Các máy chủ bộ nhớ đệm DNS trên toàn thế giới sẽ phản hồi để cho bạn biết kết quả được lưu trong bộ nhớ đệm của họ là gì. Bạn nên kiểm tra định kỳ các kết quả này cho đến khi phần lớn phản hồi bằng giá trị CNAME được chỉ định của bạn.Cấu hình CDN hoặc máy chủ Reverse Proxy riêng của bạn#
Điều này chỉ áp dụng nếu bạn đã chọn tùy chọn Reverse Proxy ở bước trước.
Cấu hình AWS CloudFront làm reverse proxy#
Bạn có thể sử dụng dịch vụ CDN do các nhà cung cấp đám mây như AWS CloudFront, Cloudflare Enterprise cung cấp để thiết lập nó làm máy chủ reverse proxy riêng của bạn.Trong ví dụ sau, chúng ta sẽ cấu hình AWS CloudFront làm Reverse Proxy.1.
Đăng nhập vào AWS và điều hướng đến CloudFront. Nhấp vào Create Distribution. 2.
Cấu hình cài đặt distribution của bạn. Dưới đây là các giá trị bạn cần thay đổi.
| Cài đặt | Giá trị |
|---|
| Origin Domain Name | Đặt thành {projectId}.apidog.io |
| Name | Mô tả cho origin. Giá trị này cho phép bạn phân biệt giữa nhiều origin trong cùng một distribution và do đó phải là duy nhất. |
| Origin Protocol Policy | Đặt thành chỉ HTTP |
| Alternate Domain Names (CNAMEs) | Đặt thành tên domain tùy chỉnh của bạn (chính là tên bạn đã cấu hình trong cài đặt Publish trong quá trình thiết lập domain tùy chỉnh) |
| SSL Certificate | Đặt thành SSL Certificate cho domain tùy chỉnh của bạn được lưu trữ trong AWS Certificate Manager (ACM). |
3.
Cung cấp thông tin về Origin Custom Headers (các trường Header Name và Value chỉ xuất hiện sau khi bạn đã cung cấp Origin Domain Name)
| Header Name | Giá trị |
|---|
| X-Apidog-Project-ID | Đặt thành {projectId} |
Bạn có thể tìm giá trị projectId trong cài đặt dự án Apidog.
4.
Cấu hình Default Cache Behavior Settings. Dưới đây là các giá trị bạn cần thay đổi.
| Cài đặt | Giá trị |
|---|
| Viewer Protocol Policy | Chọn Redirect HTTP to HTTPS |
| Allowed HTTP Methods | Chọn GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE. |
| Cache and origin request settings | Chọn Use legacy cache settings. Chọn All cho Headers, Query strings và Cookies |
5.
Không bật AWS Web Application Firewall (WAF).
6.
Nhấp vào Create distribution ở cuối trang. Bạn sẽ thấy distribution mới tạo trong danh sách CloudFront Distributions của mình. Lưu ý rằng Status sẽ hiển thị In progress cho đến khi distribution được Deployed.
7.
Thêm bản ghi CNAME mới vào DNS của bạn cho domain tùy chỉnh, trỏ đến CloudFront Domain Name cho Distribution của bạn. Bạn có thể tìm thấy giá trị này bằng cách nhấp vào Distribution ID của bạn, trong tab General, Distribution domain name (ví dụ: fd1fbc7cac6197.cloudfront.net).
Cấu hình máy chủ reverse proxy riêng của bạn#
Bạn có thể cấu hình máy chủ reverse proxy riêng cho tài liệu API của mình. Trong ví dụ sau, chúng ta sẽ sử dụng Nginx làm máy chủ reverse proxy.1.
Thêm nội dung sau vào tệp cấu hình Nginx để cấu hình đơn giản.
:8080 {
handle_path /* {
reverse_proxy http://{projectId.apidog.io {
header_up X-Apidog-Project-ID {projectId}
header_up Host "docs.example.com"
}
}
}
}
Bạn có thể tìm giá trị {projectId} trong cài đặt dự án Apidog.
2.
Cấu hình bản ghi DNS cho tên domain tùy chỉnh của bạn để trỏ đến máy chủ reverse proxy của bạn.
Triển khai tài liệu API vào thư mục con của domain tùy chỉnh#
Reverse Proxy của Apidog cho phép triển khai tài liệu API vào thư mục con của domain tùy chỉnh. Ví dụ, bạn có thể triển khai tài liệu vào đường dẫn /api-docs trên một domain như https://example.com. Khi người dùng truy cập https://example.com/api-docs, họ sẽ truy cập tài liệu API trực tuyến được Apidog lưu trữ.Các bước cấu hình:#
1.
Trên trang cài đặt Custom Domain của Apidog, nhập domain tùy chỉnh của bạn.
2.
Chọn Reverse Proxy và bật Use Subdirectory, sau đó nhập đường dẫn thư mục con.
3.
Tiếp theo, bạn cần sửa đổi tệp cấu hình của máy chủ web. Giả sử bạn đang sử dụng Nginx để proxy dịch vụ của mình, bạn có thể tham khảo cấu hình sau:
proxy_pass: Chuyển tiếp yêu cầu của client đến một máy chủ khác (chẳng hạn như máy chủ tài liệu API của Apidog).
proxy_set_header: Thiết lập các header yêu cầu được máy chủ proxy gửi đến máy chủ upstream, đ ảm bảo yêu cầu được xử lý đúng cách.
/api-docs/ là thư mục con của domain tùy chỉnh và phải kết thúc bằng / trong cấu hình Nginx.
http://{projectId}.apidog.io/ cũng phải kết thúc bằng /.
Thay thế {projectId} bằng ID dự án Apidog của bạn.
docs.example.com là domain tùy chỉnh mẫu. Thay thế bằng domain tùy chỉnh thực tế của bạn.
Sau khi cấu hình, bạn cần khởi động lại Nginx trên máy chủ của mình.
Bật HTTPS#
Tài liệu trực tuyến của Apidog hỗ trợ giao thức HTTPS, có một số lợi thế so với HTTP:Truyền dữ liệu an toàn: HTTPS sử dụng mã hóa SSL/TLS để đảm bảo an toàn cho việc truyền dữ liệu, ngăn bên thứ ba chặn bắt thông tin.
Tối ưu hóa SEO: Trình thu thập dữ liệu của công cụ tìm kiếm ưu tiên sử dụng HTTPS vì giao thức này cung cấp khả năng bảo mật và bảo vệ quyền riêng tư tốt hơn. Do đó, các trang web HTTPS có thể có độ uy tín cao hơn trong xếp hạng công cụ tìm kiếm so với các trang web HTTP.
Các bước bật HTTPS:#
1.
Đi đến trang Publish và mở tab Custom Domain.
2.
Bật HTTPS để kích hoạt HTTPS, và tùy chọn, bạn có thể bật Always Use HTTPS để ngăn giao tiếp bị chiếm đoạt hoặc bị tấn công man-in-the-middle.
Quản lý SSL Certificate#
Sau khi HTTPS được bật, bạn có thể chọn cách quản lý SSL certificate của mình:Generated by Apidog: Apidog sẽ tự động tạo SSL certificate.
Use Your Own Certificate: Bạn có thể tải lên SSL certificate và private key do tổ chức chứng thực cấp (ví dụ: Let's Encrypt). Khắc phục sự cố#
Nếu bạn gặp sự cố khi thiết lập domain tùy chỉnh, vui lòng liên hệ với chúng tôi qua Discord.Bạn có đang sử dụng Apidog Europe không?#
Nếu bạn đang sử dụng Apidog Europe, vui lòng đảm bảo rằng bạn đang sử dụng domain chính xác cho thiết lập domain tùy chỉnh của mình.Domain chính xác cho Apidog Europe trong thiết lập trước đây là {projectId}.eu.apidog.com. 
