Tài liệu API sẽ lỗi thời ngay khi ai đó chỉnh sửa một đặc tả (spec) và quên tạo lại tài liệu tham chiếu. Giải pháp là ngừng coi việc tạo tài liệu là một bước thủ công. Nếu bạn có thể tạo tài liệu chỉ với một lệnh duy nhất, bạn có thể tích hợp lệnh đó vào CI và cho phép nó chạy trên mỗi lần hợp nhất (merge).
Thực hiện việc này từ terminal còn có những lợi ích khác. Các lệnh có thể được viết script, chúng để lại một bản diff mà bạn có thể xem xét, và một tác nhân AI hoặc trình chạy CI có thể kích hoạt chúng mà không cần ai đó mở trình duyệt. Không cần nhấp chuột vào giao diện đồ họa, không cần phải nhớ "bạn đã nhấn xuất chưa".
Hướng dẫn này trước hết trình bày lộ trình phổ biến: biến một tệp OpenAPI thành một tài liệu tham chiếu HTML độc lập hoặc một tệp Markdown chỉ với một lệnh duy nhất. Sau đó, nó đi sâu hơn vào lộ trình CLI của Apidog, công cụ này trực tiếp lấy tài liệu của bạn từ một dự án đang hoạt động để nguồn dữ liệu gốc và kết quả đầu ra luôn đồng bộ. Nếu bạn muốn tìm hiểu thêm về tổng quan thị trường, hãy xem tổng hợp của chúng tôi về các công cụ tài liệu REST API hàng đầu và các công cụ tài liệu API miễn phí đáng biết.
Bạn cần một thứ để thực hiện theo: một tệp OpenAPI 3.x. Hầu hết các lệnh này đều chấp nhận openapi.yaml hoặc openapi.json một cách linh hoạt.
Xây dựng tài liệu tham chiếu HTML với Redocly CLI
Redocly CLI là cách nhanh nhất để biến một mô tả OpenAPI thành một trang HTML hoàn chỉnh, tự chứa. Nó hiển thị đặc tả của bạn bằng Redoc và ghi mọi thứ (kiểu dáng, script và nội dung) vào một tệp duy nhất mà bạn có thể lưu trữ ở bất cứ đâu hoặc gửi email cho đồng nghiệp.
Cài đặt nó trên toàn hệ thống, hoặc bỏ qua cài đặt và chạy nó với npx:
npm install @redocly/cli -g
Sau đó trỏ nó đến đặc tả của bạn:
redocly build-docs openapi.yaml
Theo mặc định, lệnh này sẽ ghi redoc-static.html vào thư mục hiện tại. Mở tệp đó trong trình duyệt và bạn sẽ có một tài liệu tham chiếu API ba bảng hoàn chỉnh. Để kiểm soát tên tệp hoặc đường dẫn, hãy sử dụng --output:
redocly build-docs openapi.yaml --output docs/index.html
Đó là toàn bộ quy trình làm việc. Một tệp đầu vào, một lệnh, một thành phẩm HTML. Nó hoạt động với các mô tả Swagger 2.0 và OpenAPI 3.0/3.1, vì vậy hầu hết các đặc tả hiện có đều được hiển thị mà không cần thay đổi. Sự đánh đổi là phạm vi: build-docs chỉ cung cấp cho bạn một trang tham chiếu chứ không phải thứ gì khác. Các hướng dẫn dài, hướng dẫn sử dụng và trang bắt đầu nằm ngoài phạm vi này.
Tạo Markdown với Widdershins
Đôi khi bạn không muốn HTML. Bạn muốn Markdown mà bạn có thể đưa vào một trang tài liệu, một trình tạo trang tĩnh, hoặc thư mục docs/ của một kho lưu trữ. Widdershins chuyển đổi một định nghĩa OpenAPI, Swagger, hoặc AsyncAPI thành Markdown tương thích với Slate.
Cài đặt từ npm:
npm install -g widdershins
Sau đó chuyển đổi đặc tả của bạn, gửi đầu ra vào một tệp với -o:
widdershins openapi.yaml -o api.md
Bỏ qua -o và Widdershins sẽ in ra stdout, điều này tiện lợi nếu bạn muốn chuyển nó đến nơi khác. Bạn cũng có thể bật/tắt các tab ngôn ngữ cho các mẫu mã:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins rất phù hợp khi quy trình tài liệu của bạn ưu tiên Markdown. Nếu bạn đang xây dựng một luồng xuất Markdown rộng hơn, hướng dẫn của chúng tôi về cách sử dụng trình tạo tài liệu API với xuất Markdown sẽ bao gồm các công cụ xung quanh. Vấn đề với cả Redocly và Widdershins đều giống nhau: chúng đọc một tệp tĩnh. Nếu định nghĩa API của bạn nằm trong một công cụ thiết kế và khác biệt so với tệp trên đĩa, thì bạn đang tài liệu hóa đặc tả của ngày hôm qua.
Tạo tài liệu từ một dự án đang hoạt động với Apidog CLI
Đây là lúc lộ trình tích hợp phát huy tác dụng. Apidog không phải là mã nguồn mở, nhưng gói miễn phí của nó cộng với apidog-cli mang đến cho bạn một giải pháp thay thế cho việc ghép nối các công cụ riêng lẻ: các endpoint, schema và tài liệu viết tay của bạn đều nằm trong một dự án, và CLI xuất dữ liệu từ dự án đó theo yêu cầu. Không có sự sai lệch nào xảy ra, bởi vì quá trình xuất đọc cùng một nguồn mà nhóm của bạn chỉnh sửa.
Cài đặt CLI từ npm:
npm install -g apidog-cli
Nếu bạn đang thiết lập lần đầu, hướng dẫn cài đặt Apidog CLI của chúng tôi bao gồm các phiên bản Node và thiết lập PATH. Sau đó, xác thực một lần bằng mã thông báo truy cập cá nhân:
apidog login --with-token <TOKEN>
Mã thông báo được lưu trữ, vì vậy bạn không cần truyền nó trong mỗi lần gọi. Từ đây, mọi thứ đều chạy dựa trên ID dự án. Thêm --help vào bất kỳ lệnh nào để xem các cờ chính xác của nó trước khi bạn chạy.
Nhập một đặc tả vào dự án
Nếu API của bạn đã có trong một tệp OpenAPI, hãy đưa nó vào một dự án để CLI có thứ để xuất:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import chấp nhận các định dạng OpenAPI 3.x, Swagger 2.0, Postman và Apidog, vì vậy bạn có thể nhập một Postman collection hoặc một xuất Apidog hiện có theo cùng một cách. Khi đặc tả được nhập, nó trở thành nguồn trực tiếp mà mọi thứ khác đọc từ đó.
Xuất tài liệu dễ đọc
Đây là lệnh cốt lõi. apidog export ghi ra các định dạng OpenAPI, HTML, Markdown hoặc Postman, vì vậy hãy chạy --help trước để xem chính xác định dạng và các cờ đầu ra mà phiên bản của bạn hỗ trợ, sau đó xuất tài liệu của dự án sang Markdown:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Mở api-docs.md và bạn có một tài liệu tham chiếu đầy đủ được tạo từ trạng thái hiện tại của dự án. Muốn HTML thay vì Markdown? Thay đổi một cờ:
apidog export --project <projectId> --format html --output ./api-docs.html
Bạn cũng có thể xuất lại sang OpenAPI khi muốn có một đặc tả di động để chuyển giao cho các bên khác:
apidog export --project <projectId> --format openapi --output ./openapi.json
Nếu dự án của bạn chứa nhiều dịch vụ và bạn chỉ muốn tài liệu hóa một phần, chức năng xuất hỗ trợ thu hẹp phạm vi. Kiểm tra apidog export --help để biết các cờ phạm vi và ID trong phiên bản của bạn, vì một dự án duy nhất có thể xuất một tệp tài liệu cho mỗi dịch vụ theo cách đó.
Quản lý các hướng dẫn đã viết, không chỉ tài liệu tham chiếu
Một tài liệu tham chiếu được tạo từ schema của bạn chỉ là một nửa câu chuyện. Nửa còn lại là phần văn xuôi: hướng dẫn bắt đầu, hướng dẫn xác thực, ghi chú di chuyển. Trong Apidog, những tài liệu đó nằm trong cây tài liệu của dự án dưới dạng tài liệu Markdown, và CLI quản lý chúng bằng nhóm lệnh doc.
Hãy bắt đầu bằng cách đọc trợ giúp của nhóm lệnh để bạn sử dụng các cờ chính xác mà phiên bản của bạn hỗ trợ:
apidog doc --help
apidog doc list --project <projectId>
Từ đó, luồng hoạt động có hình dạng tương tự như mọi thứ khác trong CLI: chạy lệnh đối với dự án của bạn, đọc kết quả JSON và làm theo agentHints.nextSteps mà nó trả về. Khi một lệnh yêu cầu tải trọng JSON, CLI có thể in ra schema mà nó mong đợi và xác thực tệp của bạn với schema đó trước khi bạn gửi bất cứ thứ gì, để bạn phát hiện một trường bị thiếu trên máy của mình thay vì trong một cuộc gọi không thành công. Kiểm tra apidog cli-schema --help để biết lệnh con xác thực chính xác.
Xuất bản trang tài liệu
Khi tài liệu tham chiếu và hướng dẫn đã sẵn sàng, bạn cũng có thể quản lý tài liệu đã xuất bản từ terminal. Hai lệnh sẽ giải quyết vấn đề này, và đọc trợ giúp của chúng trước sẽ giúp bạn tránh đoán sai cờ:
apidog docs-site --help
apidog shared-doc --help
Một lưu ý về đặt tên thường khiến mọi người bối rối: doc là một tài liệu Markdown bên trong cây API của dự án, docs-site quản lý trang tài liệu công khai, được lưu trữ, và shared-doc quản lý các liên kết tài liệu có thể chia sẻ. Hãy sử dụng docs-site khi bạn muốn một trang công khai được định nghĩa từ terminal thay vì nhấp chuột trong giao diện người dùng, và shared-doc khi bạn chỉ muốn một liên kết để gửi cho đối tác. Lợi ích là việc xuất bản trở thành một bước được script hóa: khi đặc tả của bạn thay đổi, bạn nhập lại hoặc chỉnh sửa dự án, sau đó chạy lệnh xuất bản một lần nữa, và các tài liệu được lưu trữ sẽ phản ánh bản cập nhật.
Tích hợp nó vào CI
Lý do để chạy bất kỳ thứ gì này từ CLI là khả năng lặp lại. Một khi các lệnh hoạt động cục bộ, chúng sẽ hoạt động trong một pipeline. Một bước GitHub Actions tối thiểu để tạo lại và commit tài liệu tham chiếu Markdown của bạn trên mỗi lần đẩy (push) sẽ trông như thế này:
- name: Regenerate API docs
run: |
npm install -g apidog-cli
apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Thay thế bằng redocly build-docs hoặc widdershins và cấu trúc sẽ tương tự. Tài liệu không còn là một công việc mà ai đó phải nhớ làm, mà trở thành một thành phẩm xây dựng tự động tạo lại. Để xem tài liệu tham chiếu lệnh đầy đủ, hãy xem hướng dẫn đầy đủ về Apidog CLI.
Những vướng mắc thường gặp
ID dự án sai hoặc thiếu. Mỗi lệnh Apidog export, doc và docs-site đều cần --project <projectId>. ID nằm trong cài đặt dự án, không phải tên dự án dễ đọc. Nếu một lệnh báo lỗi về dự án, đó gần như luôn là nguyên nhân.
Mã thông báo (Token) chưa được đặt trong CI. apidog login lưu trữ mã thông báo trên máy chạy nó. Trong một trình chạy CI mới, không có mã thông báo nào được lưu trữ, vì vậy bạn phải chạy login --with-token trong cùng một job trước khi thực hiện bất kỳ thao tác xuất nào. Lưu mã thông báo dưới dạng một bí mật, không bao giờ trong tệp workflow.
Xuất tệp lỗi thời. Redocly và Widdershins đọc bất kỳ tệp nào bạn cung cấp cho chúng. Nếu tệp openapi.yaml của bạn đã cũ, thì tài liệu của bạn cũng vậy. Đây chính xác là sự sai lệch mà lộ trình Apidog tránh được bằng cách xuất từ dự án trực tiếp thay vì từ một tệp trên đĩa.
Đoán cờ thay vì đọc --help. Các cờ chính xác cho export, doc, docs-site và shared-doc có thể khác nhau tùy theo phiên bản CLI. Hãy chạy apidog <command> --help và làm việc dựa trên những gì nó hiển thị thay vì một cờ bạn nhớ mang máng. Việc này chỉ mất hai giây và giúp bạn tránh một bản dựng thất bại.
Tóm lại
Việc tạo tài liệu API từ terminal phụ thuộc vào việc chọn đầu ra phù hợp. Hãy tìm đến Redocly CLI khi bạn muốn một tài liệu tham chiếu HTML độc lập, Widdershins khi bạn muốn Markdown cho một trang tài liệu, và Apidog CLI khi bạn muốn cả tài liệu tham chiếu, hướng dẫn bằng văn bản và một trang web đã xuất bản, tất cả được xuất từ một nguồn sống. Lựa chọn cuối cùng là lựa chọn giúp tài liệu của bạn trung thực, vì bản xuất và thứ mà nhóm của bạn chỉnh sửa là cùng một dự án.
Mọi lệnh ở đây đều có thể được viết script, điều đó có nghĩa là mỗi lệnh đều có thể được đưa vào CI. Thiết lập một lần và tài liệu của bạn sẽ tự động tạo lại sau mỗi thay đổi. Tải xuống Apidog để có CLI và thử quy trình xuất trên dự án của riêng bạn, hoặc đọc thêm về cách Apidog phù hợp với quy trình làm việc API-first.