Tài liệu API chuyên nghiệp xứng đáng có một tên miền chuyên nghiệp. Theo mặc định, tài liệu Apidog có thể truy cập trên tên miền <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 tên miền riêng, cho phép đối tượng người dùng của bạn truy cập tài liệu trên một tên miền phù hợp với thương hiệu của tổ chức.
Để truy cập cài đặt tên miền tùy chỉnh, hãy điều hướng đến menu Publish Docs trong thanh bên, sau đó vào trang cài đặt Publish. Bạn sẽ thấy phần Custom Domain, nơi bạn có thể nhấp vào nút Edit để bắt đầu thiết lập.
Có hai loại tùy chọn để thiết lập tên miền tùy chỉnh:
1.
CNAME (Khuyến nghị): Dễ thiết lập và duy trì nhất; hoạt động cho cả tên miền phụ và tên miền gốc, mang lại tính linh hoạt tối đa.
2.
Reverse Proxy (Nâng cao): Yêu cầu sử dụng Content Delivery Network (CDN) hoặc thiết lập reverse proxy trên máy chủ riêng của bạn; được khuyến nghị cho người dùng quen thuộc với các công nghệ này.
Tên trường và các bước cấu hình có thể khác nhau giữa các bảng điều khiển DNS, nhưng các khái niệm cốt lõi vẫn giống nhau. 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. Tại đây, bạn cần chọn CNAME.
name hoặc DNS entry là nơi bạn nhập tên miền phụ 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 đứng trước tên miền apex của bạn (ví dụ: docs). Nếu bạn không chắc nên dùng định dạng nào, hãy kiểm tra với nhà cung cấp DNS.
target, value hoặc destination là nơi tên miền phụ sẽ được trỏ đến. Bạn sẽ thấy giá trị này trong cài đặt Publish của Apidog khi chọn tùy chọn DNS CNAME. Giá trị này sẽ có dạng tương tự {docsSiteId}.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 nghị chọn Auto hoặc giữ nguyên giá trị mặc định.
Dưới đây là ví dụ về cấu hình đúng trong bảng điều khiển của Cloudflare:
Bản ghi CNAME không thể cùng tồn tại với một bản ghi khác có cùng tên. Nếu bạn đã có bản ghi A, bản ghi AAAA, bản ghi TXT hoặc bất kỳ loại bản ghi nào khác cho tên miền phụ đã chọn, bạn cần xóa các bản ghi đó trước, trước khi thêm bản ghi CNAME.
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 tính năng proxy của Cloudflare (đám mây màu cam, còn được gọi là "Proxy status" trong cài đặt tên miền của bạn) được tắt. Điều này vì hai lý do:
Tùy chọn này che giấu DNS target của tên miền của bạn khỏi công chúng, khiến Apidog không thể thực hiện đúng các kiểm tra định kỳ trên tên miền tùy chỉnh của bạn.
Tên miền tùy chỉnh của bạn đã được hưởng lợi từ CDN.
Một lần nữa, vui lòng tắt Cloudflare proxying để đảm bảo tài liệu của bạn được phục vụ mà không gặp sự cố.
Câu trả lời ngắn gọn: bạn có thể cần chờ từ 10 phút đến 48 giờ để các thay đổi DNS có hiệu lực trước khi chuyển sang bước tiếp theo.Còn nhớ trường TTL (Time To Live) mà chúng tôi đã đề cập trước đó không? Các 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 chờ bộ nhớ đệm hết hạn trước khi kiểm tra các thay đổi 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à 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 lâu 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 quy trình này, được gọi là propagation? Bạn có thể sử dụng công cụ tra cứu DNS, chẳng hạn như WhatsMyDNS. Nhập đầy đủ tên miền phụ 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ả đã 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 gán cho bạn.
Cấu hình CDN hoặc máy chủ Reverse Proxy riêng của bạn#
Phạm vi áp dụng
Phần này chỉ áp dụng nếu bạn đã chọn tùy chọn Reverse Proxy ở bước trước.
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 làm máy chủ reverse proxy của riêng 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 {docsSiteId}.apidog.io
Name
Mô tả cho origin. Giá trị này giú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 miền tùy chỉnh của bạn (cùng tên miền bạn đã cấu hình trong cài đặt Publish trong quá trình thiết lập tên miền tùy chỉnh)
SSL Certificate
Đặt thành SSL Certificate cho tên miền tùy chỉnh của bạn được lưu trữ trong AWS Certificate Manager (ACM).
3.
Cung cấp thông tin trong 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-Docs-Site-ID
Đặt thành {docsSiteId}
{docsSiteId} là Docs Site ID của bạn, có thể tìm thấy trong bảng điều khiển tên miền tùy chỉnh. Vui lòng đảm bảo nhập đúng ID.
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. Lưu ý rằng Status sẽ hiển thị In progress cho đến khi distribution được Deployed.
7.
Thêm một bản ghi CNAME mới vào DNS của bạn cho tên miền tùy chỉnh, trỏ đến CloudFront Domain Name của Distribution. Bạn có thể tìm thấy thông tin này bằng cách nhấp vào Distribution ID của bạn, trong tab General, mục Distribution domain name (ví dụ: fd1fbc7cac6197.cloudfront.net).
Bạn có thể sử dụng Cloudflare Workers để hoạt động như một reverse proxy. Điều này cho phép bạn giữ tên miền ở trạng thái được proxy (Orange Cloud) trong khi vẫn đảm bảo Apidog nhận được các định danh dự án cần thiết.
Nhấp vào Create Application, sau đó Create Worker. (Tiếp tục với Start with Hello World!, nếu được nhắc chọn phương thức)
3.
Đặt tên cho worker của bạn (ví dụ: apidog-docs-proxy) và nhấp vào Deploy.
4.
Nhấp vào Edit Code và thay thế script hiện có bằng nội dung sau:
Bạn có thể tìm thấy {docsSiteId} trong bảng điều khiển tên miền tùy chỉnh. Vui lòng đảm bảo nhập đúng ID vào cả hai biến targetHost và docsSiteId.
5.
Nhấp vào Save and Deploy.
6.
Điều hướng đến tab Settings của Worker, chọn Domains & Routes, rồi nhấp vào nút +Add.
7.
Nhập tên miền tùy chỉnh của bạn (ví dụ: docs.example.com). Cloudflare sẽ tự động xử lý các bản ghi DNS và chứng chỉ SSL.
8.
Đảm bảo SSL/TLS encryption mode của Cloudflare được đặt thành Full hoặc Full (Strict) để cho phép giao tiếp bảo mật giữa Cloudflare và Apidog.
Điều kiện tiên quyết
Trước khi gắn tên miền tùy chỉnh vào worker, hãy đảm bảo tên miền (ví dụ: example.com) đã được thêm vào tài khoản Cloudflare của bạn và nameserver của nó đang hoạt động.
{docsSiteId} là Docs Site ID của bạn, có thể tìm thấy trong bảng điều khiển tên miền tùy chỉnh. Vui lòng đảm bảo nhập đúng ID.
2.
Cấu hình bản ghi DNS cho tên miền tùy chỉnh của bạn để trỏ đến máy chủ reverse proxy.
Triển khai tài liệu API vào thư mục con của tên miền tùy chỉnh#
Reverse Proxy của Apidog cho phép tài liệu API được triển khai vào thư mục con của một tên miền 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 tên miền 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 do Apidog lưu trữ.
Tài liệu trực tuyến của Apidog hỗ trợ giao thức HTTPS, có một số ưu điểm 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 quá trình truyền dữ liệu, ngăn bên thứ ba chặn 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 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.
Nếu bạn đang sử dụng Apidog Europe, vui lòng đảm bảo rằng bạn đang sử dụng đúng tên miền cho quá trình thiết lập tên miền tùy chỉnh.Tên miền đúng cho Apidog Europe trong thiết lập trước đây là {docsSiteId}.eu.apidog.com.