Bảo Mật Tài Liệu API: Đặc Tả API Có An Toàn Trong Git?

Bảo mật tài liệu API là một phần trong chương trình API của bạn mà hầu như không ai kiểm tra. Bạn củng cố chính API đó bằng xác thực, giới hạn tốc độ và kiểm tra bảo mật. Nhưng các tài liệu mô tả API đó, thông số kỹ thuật OpenAPI, trang Swagger UI, bản markdown giải thích luồng xác thực của bạn, thường nằm trong kho lưu trữ Git hoặc trên một máy chủ tĩnh mà không ai xem xét kể từ ngày nó được thiết lập. Vào ngày 20 tháng 5 năm 2026, GitHub xác nhận rằng những kẻ tấn công đã đánh cắp dữ liệu từ khoảng 3.800 kho mã nội bộ của họ. Điểm đột nhập là một tiện ích mở rộng VS Code bị nhiễm độc được cài đặt trên máy tính xách tay của một nhân viên GitHub. Vi phạm đó là một lý do chính đáng để đặt ra một câu hỏi khó chịu về thiết lập của riêng bạn: nếu ai đó có thể lặng lẽ thay đổi tài liệu API đã xuất bản của bạn, bạn có nhận ra không, và người dùng API của bạn có nhận ra không?

TL;DR

Tài liệu API an toàn có nghĩa là tài liệu của bạn có kiểm soát truy cập, lịch sử phiên bản, tính toàn vẹn mà bạn có thể xác minh và một dấu vết kiểm toán, để một kho lưu trữ hoặc máy chủ bị xâm phạm không thể âm thầm cung cấp các điểm cuối, mã thông báo hoặc hướng dẫn xác thực sai cho các nhà phát triển sao chép chúng vào sản xuất. Docs-as-code trong Git là tốt cho nhiều nhóm và cung cấp cho bạn khả năng xem xét và lịch sử miễn phí. Nó trở thành một rủi ro khi kho lưu trữ là công khai mà không có kiểm soát truy cập, khi các thông số kỹ thuật cũ trôi dạt khỏi API trực tiếp, hoặc khi một ví dụ bị giả mạo đến tay người dùng mà không bị phát hiện. Một lớp tài liệu được quản lý như Apidog bổ sung bảo vệ bằng mật khẩu, danh sách cho phép IP và email, tên miền tùy chỉnh, tạo phiên bản và một thông số kỹ thuật được đồng bộ hóa với thiết kế API của bạn như là nguồn đáng tin cậy duy nhất.

Tại sao vụ vi phạm của GitHub nên khiến bạn xem xét tài liệu API của mình

Sự cố GitHub đáng để tìm hiểu trước khi bạn hoảng sợ về nó. Nhóm tấn công TeamPCP đã đánh cắp các kho lưu trữ nội bộ của GitHub và hiện đang bán bộ dữ liệu này với giá hơn 50.000 đô la trên một diễn đàn ngầm. Thông tin từ BleepingComputer xác nhận tiện ích mở rộng VS Code độc hại đến trực tiếp từ marketplace chính thức và chạy trên thiết bị của một nhân viên. GitHub cho biết họ không tìm thấy bằng chứng nào cho thấy dữ liệu khách hàng được lưu trữ bên ngoài các kho lưu trữ nội bộ của họ bị ảnh hưởng, và cuộc điều tra vẫn đang tiếp diễn.

Sự cố này đưa ra cho bạn một lời nhắc nhở. Đó là một lời nhắc nhở để xem xét tài liệu API của bạn đang ở đâu và được lưu trữ như thế nào, và liệu nó có thể bị giả mạo hay không. Hầu hết các nhóm chưa bao giờ hỏi điều đó. Họ đã xuất bản Swagger UI lên GitHub Pages ba năm trước, trỏ một CNAME vào đó, và tiếp tục công việc. Kho lưu trữ là công khai. Thông số kỹ thuật là bất cứ thứ gì được hợp nhất lần cuối. Không ai xem xét các thay đổi đối với trang tài liệu với sự cẩn trọng tương tự như họ áp dụng cho mã ứng dụng.

Khoảng trống đó quan trọng vì tài liệu API là hướng dẫn. Khi một nhà phát triển tích hợp với API của bạn, họ sao chép các đường dẫn điểm cuối, cấu trúc yêu cầu, tiêu đề xác thực và thường là các giá trị ví dụ trực tiếp từ tài liệu của bạn vào mã của họ. Nếu một kẻ tấn công có thể thay đổi những hướng dẫn đó, họ không làm biến dạng một trang tiếp thị. Họ đang chỉnh sửa mã mà người khác sẽ chạy. Logic tương tự xuất hiện trong các bài đánh giá sau sự cố của các vụ vi phạm khác năm 2026; bài viết của chúng tôi về các bài học về bảo mật API từ vụ vi phạm Vercel đề cập đến cách một thay đổi nhỏ trong một bề mặt đáng tin cậy lan rộng.

Bài viết này trình bày bốn điều: những cách cụ thể mà tài liệu API bị xâm phạm gây hại cho người dùng của bạn, khi nào docs-as-code trong Git thực sự tốt so với khi nó trở thành một trách nhiệm, "tài liệu API an toàn" thực sự có nghĩa là gì dưới dạng một danh sách kiểm tra, và cách một lớp tài liệu được quản lý khắc phục các lỗ hổng. Hai bài viết liên quan đi sâu hơn vào các khía cạnh liên quan: vụ vi phạm GitHub có ý nghĩa gì đối với các công cụ API tự lưu trữ và bảo mật khóa API tiện ích mở rộng VS Code.

Điều gì xảy ra sai khi kho lưu trữ hoặc máy chủ tài liệu API của bạn bị xâm phạm

Bắt đầu với mô hình mối đe dọa. Tài liệu API của bạn nằm trên một bề mặt nào đó: một kho lưu trữ Git, một quy trình CI xây dựng chúng, và một máy chủ phục vụ chúng. Xâm phạm bất kỳ điều nào trong số đó và một vài kết quả xấu cụ thể sẽ xảy ra. Không có điều nào trong số đó là lý thuyết.

Giả mạo tài liệu ảnh hưởng đến mã sản xuất

Đây là trường hợp tồi tệ nhất và ít rõ ràng nhất. Một kẻ tấn công có quyền ghi vào kho lưu trữ tài liệu của bạn, hoặc vào máy chủ phục vụ trang web đã xây dựng, thực hiện một chỉnh sửa nhỏ. Chúng thay đổi https://api.payments.acme.com/v2/charge thành một tên miền mà chúng kiểm soát. Chúng thay thế mã thông báo bearer ví dụ trong trang "Bắt đầu" của bạn bằng một mã thông báo chuyển hướng qua proxy của chúng. Chúng viết lại một câu duy nhất trong phần OAuth của bạn để việc trao đổi mã thông báo gửi đến URL sai.

Không có điều nào trong số đó làm hỏng trang web của bạn. Trang vẫn hiển thị. CI vẫn vượt qua, vì thông số kỹ thuật vẫn là YAML hợp lệ. Nhưng nhà phát triển tiếp theo tích hợp với API của bạn sẽ sao chép điểm cuối đó hoặc luồng đó vào dịch vụ của họ. Thay đổi đó hiện đang chạy trong môi trường sản xuất của họ, và họ tin tưởng nó vì nó đến từ tài liệu chính thức của bạn.

Hãy xem xét một đoạn OpenAPI thực tế. Một nhóm tài liệu hóa một điểm cuối thanh toán như sau:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Một chỉnh sửa nhỏ đối với URL servers đó, được hợp nhất thông qua một tài khoản bị xâm phạm hoặc đẩy lên một máy chủ bị chiếm quyền, và mọi người dùng tạo lại một client từ thông số kỹ thuật bây giờ gửi dữ liệu thẻ đến tên miền của kẻ tấn công. Sự khác biệt chỉ là hai từ. Không ai đánh dấu hai từ trong một commit tài liệu.

Điểm cuối nội bộ và không được tài liệu hóa bị rò rỉ

Các kho lưu trữ tài liệu tích lũy nhiều thứ. Một thông số kỹ thuật bắt đầu là API công khai thường phát triển các đường dẫn chỉ dành cho nội bộ, các điểm cuối quản trị, các tuyến gỡ lỗi hoặc các hoạt động chỉ dành cho đối tác mà không bao giờ có ý định công bố. Nếu kho lưu trữ là công khai, hoặc trở thành công khai do cấu hình sai, thì các điểm cuối đó bây giờ là một bản đồ cho bất kỳ ai đang quét bề mặt tấn công của bạn.

Ngay cả một kho lưu trữ riêng tư cũng là một vấn đề ở đây. Một vụ vi phạm như của GitHub làm rò rỉ các kho lưu trữ riêng tư. Ngay khi thông số kỹ thuật API nội bộ của bạn nằm trong một kho lưu trữ bị đánh cắp, kẻ tấn công có một danh sách chính xác các điểm cuối, tham số và payload dự kiến của bạn. Chúng không cần phải đoán. Bạn đã giao cho chúng schema. Nếu bạn muốn một framework để tìm các lỗ hổng này trước khi người khác làm, danh sách kiểm tra kiểm thử bảo mật API cho năm 2026 của chúng tôi được xây dựng dựa trên loại đánh giá bề mặt này.

GitHub Pages công khai không có kiểm soát truy cập

GitHub Pages là một máy chủ tĩnh. Nó phục vụ các tệp. Nó không có khái niệm về việc ai đang đọc chúng. Đối với một API thực sự công khai, điều đó là đúng và tốt. Đối với tài liệu chỉ nên hiển thị cho khách hàng trả tiền, cho một nhóm đối tác được chỉ định, hoặc cho đội ngũ của riêng bạn, đó là công cụ sai, bởi vì hoàn toàn không có cổng bảo vệ nào.

Các nhóm giải quyết vấn đề này bằng "bảo mật thông qua một URL khó đoán". Tài liệu nằm ở một đường dẫn mà không ai liên kết đến. Đó không phải là kiểm soát truy cập. URL có thể rò rỉ qua lịch sử trình duyệt, tiêu đề referrer, nhật ký proxy và dấu trang được chia sẻ. Bất kỳ ai tìm thấy liên kết đều thấy mọi thứ, mãi mãi, mà bạn không có cách nào để biết họ đã làm vậy.

Tài liệu cũ và không thể xác minh

Chế độ lỗi ít gây ồn ào hơn hoàn toàn không cần kẻ tấn công. Tài liệu trong một kho lưu trữ Git bị lệch lạc. Ai đó triển khai một thay đổi API, quên cập nhật thông số kỹ thuật, và bản markdown bây giờ mô tả một điểm cuối hoạt động khác trong sản xuất. Người dùng tích hợp dựa trên hành vi được tài liệu hóa, gặp phải hành vi thực tế, và mất một ngày để gỡ lỗi.

Khi tài liệu bị xâm phạm, vấn đề này trở nên tồi tệ hơn, vì bạn mất khả năng phân biệt sự lệch lạc với sự giả mạo. Điểm cuối đó luôn sai, hay ai đó đã thay đổi nó? Nếu không có lịch sử có thể xác minh được liên kết với thiết kế API thực tế của bạn, bạn không thể trả lời điều đó. Tài liệu trở nên không thể xác minh, và tài liệu không thể xác minh không tốt hơn nhiều so với không có tài liệu.

Khi docs-as-code trong Git là tốt, và khi nó là một rủi ro

Docs-as-code là một thực hành hợp pháp, phổ biến, và phần này không phải là một lập luận chống lại nó. Đặt thông số kỹ thuật OpenAPI và markdown của bạn vào một kho lưu trữ Git, xây dựng Swagger UI hoặc Redoc với CI, và triển khai đến một máy chủ tĩnh mang lại cho bạn những lợi ích thực sự. Bạn có thể xem xét yêu cầu kéo (pull-request review) đối với các thay đổi tài liệu. Bạn có một lịch sử đầy đủ về ai đã thay đổi gì và khi nào. Bạn có tài liệu được phiên bản hóa cùng với mã. Đó chính là những thuộc tính giúp phát hiện giả mạo, khi quy trình làm việc được tuân thủ.

Vì vậy, câu hỏi không phải là "Git hay không Git". Mà là "thiết lập cụ thể này có an toàn cho API cụ thể này không". Dưới đây là cách phân chia hai trường hợp.

Docs-as-code trong Git là tốt khi

Thực hành này hoạt động tốt trong một bộ điều kiện cụ thể:

• API hoàn toàn công khai, vì vậy không có gì để che giấu và không cần kiểm soát truy cập.
• Kho lưu trữ có bảo vệ nhánh, đánh giá bắt buộc và một nhóm nhỏ, được kiểm toán có quyền ghi.
• Các thay đổi tài liệu trải qua quá trình đánh giá nghiêm ngặt như mã, vì vậy một URL hoặc mã thông báo bị thay đổi sẽ bị phát hiện trong quá trình xem xét.
• Quy trình xây dựng được khóa: các hành động được ghim, không có bước của bên thứ ba không được xem xét, các thông tin xác thực triển khai được giới hạn phạm vi.
• Thông số kỹ thuật được tạo ra từ hoặc xác thực với API thực tế, không được chỉnh sửa thủ công và hy vọng.
• Có người chịu trách nhiệm giữ cho thông số kỹ thuật luôn cập nhật, để không có sự lệch lạc tích lũy.

Nếu tất cả những điều đó được giữ vững, tài liệu được lưu trữ trên Git là một hệ thống mạnh mẽ, minh bạch. Lịch sử là dấu vết kiểm toán của bạn. Các đánh giá là kiểm tra tính toàn vẹn của bạn.

Docs-as-code trong Git trở thành một rủi ro khi

Thiết lập tương tự trở nên rủi ro khi các điều kiện bị bỏ qua:

• Tài liệu nên là riêng tư hoặc chỉ dành cho đối tác, nhưng máy chủ không có kiểm soát truy cập, vì vậy "riêng tư" có nghĩa là "không được liên kết".
• Quyền ghi rộng rãi, hoặc bao gồm các tài khoản dịch vụ và mã thông báo CI mà không ai theo dõi.
• Các commit tài liệu được thông qua dễ dàng, vì "chỉ là tài liệu", vì vậy một khác biệt độc hại trôi qua.
• Thông số kỹ thuật được duy trì thủ công và lệch lạc so với API trực tiếp, vì vậy người dùng không thể tin cậy nó.
• Kho lưu trữ chứa các điểm cuối nội bộ hoặc không được tài liệu hóa cùng với các điểm cuối công khai.
• Không có tín hiệu toàn vẹn: không ai có thể cho bạn biết liệu trang web được triển khai có khớp với nguồn đã được xem xét hay không.

Vụ vi phạm của GitHub rơi thẳng vào những chế độ lỗi này. Cuộc tấn công đến qua một điểm cuối của nhà phát triển và tiếp cận các kho lưu trữ nội bộ. Nếu thông số kỹ thuật API riêng tư của bạn nằm trong một trong những kho lưu trữ đó, vụ vi phạm đã làm lộ schema của bạn bất kể quy trình xem xét của bạn cẩn thận đến đâu. Git cung cấp cho bạn sự minh bạch; nó không cung cấp cho bạn sự bảo mật khi chính kho lưu trữ bị đánh cắp. Để so sánh đầy đủ hơn về vị trí của các phương pháp tài liệu tự lưu trữ khác nhau về những đánh đổi này, hãy xem so sánh tài liệu API tự lưu trữ của chúng tôi.

Kết luận được cân bằng một cách có chủ đích. Hãy giữ docs-as-code nếu API của bạn là công khai và quy trình của bạn có kỷ luật. Hãy xem xét lại nếu tài liệu của bạn cần kiểm soát truy cập, nếu quy trình xem xét của bạn coi tài liệu là thứ yếu, hoặc nếu bạn không thể trả lời "liệu trang web trực tiếp có khớp với nguồn đã được xem xét hay không".

"Tài liệu API an toàn" thực sự có nghĩa là gì

"Tài liệu API an toàn" là một khái niệm mơ hồ cho đến khi bạn chia nó thành các thuộc tính có thể kiểm tra được. Bốn trong số đó là quan trọng nhất.

Kiểm soát truy cập

Tài liệu chỉ hiển thị cho những người nên xem chúng. Công khai cho một API công khai. Hạn chế cho tài liệu chỉ dành cho khách hàng, chỉ dành cho đối tác hoặc nội bộ. Hạn chế phải là một cổng thực sự, mật khẩu, danh sách cho phép IP, danh sách cho phép email hoặc SSO, chứ không phải một URL không rõ ràng. Bài kiểm tra: bạn có thể kể tên chính xác ai có thể đọc tài liệu của bạn ngay bây giờ, và thu hồi quyền truy cập của một người trong vòng chưa đầy một phút không?

Tạo phiên bản

Mọi phiên bản tài liệu đã xuất bản đều được bảo toàn và có thể nhận dạng. Người dùng API v1 của bạn thấy tài liệu v1; người dùng v2 thấy v2. Bạn có thể hiển thị tài liệu đã nói gì vào một ngày cụ thể. Bài kiểm tra: một nhà phát triển tích hợp với phiên bản API cũ hơn của bạn vẫn có thể tìm thấy tài liệu chính xác cho nó, thay vì tài liệu đã tự động cập nhật lên v2 không?

Tính toàn vẹn

Bạn có thể xác minh rằng tài liệu đã xuất bản khớp với những gì bạn mong muốn. Hoặc tài liệu được tạo từ một nguồn đáng tin cậy được kiểm soát, hoặc có một dấu vết xem xét và lịch sử đủ mạnh để một thay đổi trái phép nổi bật. Bài kiểm tra: nếu ai đó đã thay đổi một URL điểm cuối trên tài liệu trực tiếp của bạn một giờ trước, có điều gì sẽ cho bạn biết không?

Dấu vết kiểm toán

Bạn có thể trả lời ai đã thay đổi tài liệu, họ đã thay đổi gì và khi nào. Lịch sử Git cung cấp cho bạn điều này cho kho lưu trữ; bạn cũng cần điều này cho bề mặt đã xuất bản, vì bước triển khai là một điểm tấn công riêng. Bài kiểm tra: bạn có thể tạo nhật ký thay đổi cho tài liệu đã xuất bản của mình trong 90 ngày qua không?

Một thiết lập đáp ứng cả bốn điều trên là tài liệu an toàn. Tài liệu được lưu trữ trên Git có thể đạt được việc tạo phiên bản, tính toàn vẹn và dấu vết kiểm toán thông qua bảo vệ nhánh và lịch sử. Điều mà chúng thường bỏ lỡ trên một máy chủ tĩnh là kiểm soát truy cập, và lỗ hổng đó là lý do cho một lớp tài liệu được quản lý.

Apidog cung cấp cho bạn tài liệu API an toàn như thế nào

Apidog là một nền tảng API tất cả trong một để thiết kế, gỡ lỗi, kiểm thử, mô phỏng và tài liệu hóa API. Phần tài liệu được xây dựng sao cho bốn thuộc tính trên là mặc định thay vì những thứ bạn phải thêm vào. Để theo dõi, tải xuống Apidog và mở bất kỳ dự án nào có định nghĩa API.

Tài liệu đã xuất bản từ một nguồn đáng tin cậy được kiểm soát

Trong Apidog, tài liệu được tạo từ thiết kế API của bạn bên trong dự án. Bạn thiết kế các điểm cuối, schema và xác thực trong trình thiết kế trực quan, và Apidog tự động tạo tài liệu từ định nghĩa đó. Nhấn Xuất bản và bạn sẽ có một trang tài liệu tương tác với bảng điều khiển "Thử ngay" và các mẫu mã đa ngôn ngữ.

Lợi ích về tính toàn vẹn là cấu trúc. Tài liệu đã xuất bản không phải là markdown có thể chỉnh sửa riêng biệt có thể bị lệch lạc hoặc giả mạo. Chúng phản ánh định nghĩa API. Thay đổi định nghĩa, tài liệu sẽ theo. Để thay đổi những gì người dùng thấy, bạn thay đổi thiết kế bên trong dự án, vốn có các quyền và lịch sử thay đổi riêng, thay vì chỉnh sửa một tệp rời rạc trên một máy chủ tĩnh.

Kiểm soát truy cập tài liệu

Đây là nơi Apidog lấp đầy khoảng trống của GitHub Pages. Khi bạn xuất bản, bạn chọn khả năng hiển thị, và các tùy chọn là các cổng thực sự, không phải sự mơ hồ:

• Công khai: bất kỳ ai có liên kết đều có thể đọc. Chính xác cho một API thực sự mở.
• Bảo vệ bằng mật khẩu: đặt mật khẩu (hoặc tạo một mật khẩu ngẫu nhiên) và chia sẻ nó với các bên liên quan. Chỉ những người có mật khẩu mới có thể truy cập.
• Danh sách cho phép IP: hạn chế truy cập vào các IP hoặc dải IP cụ thể, chẳng hạn như văn phòng hoặc VPN của bạn. Hữu ích cho tài liệu nội bộ.
• Danh sách cho phép email: liệt kê các địa chỉ email hoặc tên miền được phép; người dùng xác minh bằng mã một lần. Các ký tự đại diện như *@yourcompany.com bao gồm toàn bộ một tổ chức.
• Đăng nhập tùy chỉnh: kết nối hệ thống xác thực của riêng bạn; máy chủ của bạn cấp JWT, Apidog xác minh nó, và quyền truy cập phụ thuộc vào tính hợp lệ.

Apidog tài liệu hóa cả năm phương pháp trong hướng dẫn kiểm soát quyền truy cập tài liệu API. Điều đó trả lời trực tiếp bài kiểm tra kiểm soát truy cập: bạn có thể nêu rõ ai có thể đọc tài liệu, và bạn có thể thu hồi mật khẩu hoặc xóa email khỏi danh sách cho phép ngay lập tức.

Tên miền tùy chỉnh

Bạn có thể phục vụ tài liệu đã xuất bản trên tên miền của riêng mình, để người dùng thấy developer.yourcompany.com thay vì một URL chung chung. Apidog hỗ trợ một tên miền tùy chỉnh thông qua DNS CNAME (phương pháp được khuyến nghị) hoặc một reverse proxy. Một tên miền tùy chỉnh riêng nó không phải là một kiểm soát bảo mật, nhưng nó giữ tài liệu của bạn trên cơ sở hạ tầng mà bạn quản lý và điều hành, thay vì rải rác trên các máy chủ không ai sở hữu.

Thông số kỹ thuật OpenAPI được giữ đồng bộ với thiết kế API của bạn

Sự lệch lạc là một vấn đề bảo mật tài liệu vì nó làm cho tài liệu không thể xác minh. Apidog coi thiết kế API là nguồn đáng tin cậy duy nhất và giữ tài liệu đồng bộ khi thiết kế thay đổi. Apidog nhập OpenAPI 3.0, 3.1 và Swagger 2.0, và hỗ trợ nhập theo lịch trình để thông số kỹ thuật bên ngoài luôn cập nhật tự động.

Nếu bạn hiện đang duy trì một thông số kỹ thuật thủ công trong một kho lưu trữ Git, đó là thiết lập có độ lệch cao nhất, khó xác minh nhất. Việc chuyển thông số kỹ thuật vào Apidog làm nguồn đáng tin cậy duy nhất có nghĩa là tài liệu đã xuất bản luôn khớp với một định nghĩa mà bạn kiểm soát. Các nhóm chuyển từ SwaggerHub có thể làm theo hướng dẫn của chúng tôi để di chuyển tài liệu API SwaggerHub sang Apidog.

Tạo phiên bản tài liệu

Apidog hỗ trợ tạo phiên bản tài liệu, vì vậy bạn xuất bản và giữ nhiều phiên bản song song. Một người dùng tích hợp với API v1 của bạn đọc tài liệu v1 chính xác ngay cả sau khi v2 được phát hành. Việc tạo phiên bản liên kết với các nhánh và lịch sử thay đổi, vì vậy sự phát triển của API và tài liệu của nó, được theo dõi. Điều đó bao gồm cả bài kiểm tra tạo phiên bản và dấu vết kiểm toán.

Không có điều nào trong số này có thể ngăn chặn TeamPCP xâm phạm máy tính xách tay của nhà phát triển. Nó có nghĩa là một điều khác: một câu trả lời rõ ràng về việc ai có thể đọc tài liệu của bạn, liệu phiên bản đã xuất bản có khớp với thiết kế của bạn hay không và những gì đã thay đổi theo thời gian. Đó là cuộc kiểm toán mà vụ vi phạm của GitHub nên thúc đẩy bạn thực hiện.

So sánh các tùy chọn lưu trữ tài liệu

So sánh nhanh các cách tiếp cận phổ biến với bốn thuộc tính bảo mật.

Không có dòng nào là đúng hoàn toàn. GitHub Pages công khai là một lựa chọn tốt cho một API công khai với một quy trình được khóa chặt. Tự lưu trữ phù hợp với các nhóm có yêu cầu về vị trí hoặc cô lập nghiêm ngặt; so sánh tài liệu API tự lưu trữ của chúng tôi và so sánh Scalar vs SwaggerHub vs Apidog trình bày chi tiết các đánh đổi đó. Vấn đề là phải lựa chọn có chủ đích dựa trên bốn thuộc tính, chứ không phải kế thừa một thiết lập từ ba năm trước và không bao giờ nhìn lại nó nữa.

Kết luận

Vụ vi phạm của GitHub không phải là lý do để từ bỏ docs-as-code hay không tin tưởng GitHub. Đó là một lời nhắc nhở để kiểm tra một bề mặt mà hầu hết các nhóm đã bỏ qua: nơi tài liệu API của bạn cư trú và liệu nó có thể bị giả mạo hay không.

Bước tiếp theo: liệt kê mọi nơi tài liệu API của bạn được xuất bản, kiểm tra từng nơi theo bốn thuộc tính, và khắc phục lỗ hổng lớn nhất. Nếu kiểm soát truy cập là lỗ hổng, hãy tải xuống Apidog và xuất bản tài liệu của một dự án với mật khẩu hoặc danh sách cho phép email để xem một lớp được quản lý xử lý nó như thế nào.