Tệp OpenAPI của bạn là nguồn sự thật cho API của bạn. Nó liệt kê mọi đường dẫn, mọi tham số, mọi hình dạng phản hồi. Vấn đề là hầu như không ai trong nhóm của bạn muốn đọc YAML hoặc JSON thô. Một kỹ sư backend muốn có một tài liệu tham khảo nhanh về điểm cuối trong kho lưu trữ. Một nhà phát triển frontend muốn có một bảng các trường yêu cầu mà họ có thể quét trong một yêu cầu kéo. Một nhà văn kỹ thuật muốn thứ gì đó họ có thể dán vào wiki mà không cần nhập lại toàn bộ lược đồ.
Markdown là định dạng phù hợp với tất cả những người đọc đó. Nó hiển thị trên GitHub, trong Confluence, trong trình tạo trang tĩnh và trong một trình soạn thảo văn bản thuần túy. Vì vậy, nhiệm vụ lặp lại là: lấy một tệp openapi.yaml đã tồn tại và biến nó thành Markdown sạch mà con người thực sự mở ra. Làm thủ công thì chậm và nó sẽ lạc hậu ngay khi ai đó thêm một điểm cuối. Làm tự động là phiên bản duy nhất tồn tại khi tiếp xúc với một chu kỳ phát hành thực tế.
Tại sao phải tạo Markdown từ OpenAPI?
Một tài liệu OpenAPI được xây dựng cho máy móc. Các công cụ phân tích nó để tạo client, chạy kiểm thử hợp đồng, xác thực yêu cầu và hiển thị tài liệu tương tác. Khả năng đọc bằng máy đó là toàn bộ mục đích, và nó đáng được bảo vệ. Nếu bạn muốn ôn lại cách giữ cho đặc tả đó luôn đúng, hướng dẫn công cụ xác thực OpenAPI sẽ đề cập đến việc linting trước khi bạn tạo bất cứ thứ gì từ nó.
Markdown giải quyết một vấn đề khác: phân phối cho con người ở những nơi không chạy trình hiển thị OpenAPI. Một vài trường hợp cụ thể xuất hiện hết lần này đến lần khác.
- Một tệp
README.mdhoặc thư mục/docstrong kho lưu trữ, để một người đóng góp mới xem danh sách điểm cuối mà không cần rời khỏi codebase. - Một mô tả yêu cầu kéo cần hiển thị những gì một điểm cuối mới chấp nhận và trả về.
- Một trang Confluence hoặc Notion nơi toàn bộ nhóm, bao gồm cả những người không phải kỹ sư, xem xét hợp đồng.
- Một trang tài liệu tĩnh được xây dựng bằng Docusaurus, MkDocs hoặc Hugo, tất cả đều chấp nhận Markdown làm đầu vào.
Từ khóa quan trọng là tự động. Một tệp Markdown bạn viết một lần rồi quên sẽ sai ngay trong sprint tiếp theo. Một tệp Markdown được tái tạo từ đặc tả sau mỗi thay đổi sẽ luôn đúng với hợp đồng mà không tốn công. Đó là sự khác biệt giữa tài liệu mà mọi người tin tưởng và tài liệu mà mọi người học cách bỏ qua.
Các phương pháp chuyển đổi, từ nhanh chóng đến chắc chắn
Không có lệnh chính thức duy nhất nào đi kèm với OpenAPI để tạo ra Markdown. Thay vào đó, có một hệ sinh thái nhỏ các công cụ chuyển đổi cộng với các công cụ tài liệu được tích hợp sẵn trong các nền tảng API. Dưới đây là bức tranh tổng quan, được sắp xếp gần đúng theo mức độ thiết lập mà mỗi công cụ yêu cầu.
| Phương pháp | Tốt nhất cho | Kết quả bạn nhận được |
|---|---|---|
openapi-to-md / openapi-markdown |
Xuất Markdown nhanh, không cần cấu hình | Một tệp Markdown hoặc bảng lược đồ duy nhất |
| Widdershins | Tài liệu kiểu Slate/Docusaurus với các tab mã | Markdown có thể tùy chỉnh theme với các mẫu ngôn ngữ |
| Một script tùy chỉnh trên đặc tả đã được phân tích cú pháp | Chính xác bố cục mà nhóm của bạn muốn | Bất cứ thứ gì bạn dùng template |
| Apidog | Nhập đặc tả, tài liệu được hiển thị và kiểm thử trong một không gian làm việc | Tài liệu được lưu trữ cộng với các khối nội dung Markdown |
Hãy chọn dựa trên mức độ kiểm soát bạn cần và nơi đầu ra phải đến. Các phần tiếp theo sẽ trình bày cách chạy từng phương pháp.
Phương pháp 1: Trình chuyển đổi mã nguồn mở một dòng
Cách nhanh nhất là sử dụng một trình chuyển đổi chuyên dụng. Hai trình nổi tiếng bao gồm thế giới Node và Python.
Đối với dự án Node, openapi-to-md lấy một tài liệu v2 hoặc v3 ở định dạng YAML hoặc JSON và ghi ra một tệp Markdown có cấu trúc. Bạn có thể chạy nó mà không cần cài đặt toàn cục:
npx openapi-to-md openapi.yaml api-reference.md
Đối với chuỗi công cụ Python, openapi-markdown thực hiện công việc tương tự với lệnh cài đặt pip và một lệnh duy nhất:
pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md
Cả hai đều đọc đặc tả, duyệt qua mọi đường dẫn và lược đồ, rồi xuất ra một tệp Markdown với các tiêu đề cho mỗi điểm cuối và các bảng cho tham số và phản hồi. Đối số tệp đầu ra là tùy chọn trong một số công cụ này; nếu bỏ qua, chúng sẽ mặc định là tên đầu vào với phần mở rộng .md. Điều đó đủ cho một tài liệu tham khảo trong kho lưu trữ mà bạn tái tạo theo yêu cầu.
Sự đánh đổi với các trình chuyển đổi nhanh là kiểm soát bố cục. Bạn nhận được cấu trúc của chúng, không phải của bạn. Nếu các bảng mặc định của chúng phù hợp với cách nhóm của bạn đọc tài liệu, bạn đã hoàn thành chỉ trong một dòng. Nếu bạn cần các mẫu mã bằng năm ngôn ngữ hoặc một thứ tự phần cụ thể, bạn sẽ muốn phương pháp tiếp theo.
Phương pháp 2: Widdershins cho tài liệu có thể tùy chỉnh theme với các mẫu mã
Widdershins là công cụ Node đã được thiết lập để chuyển đổi tệp OpenAPI hoặc Swagger thành Markdown tương thích với Slate. Đây là công cụ cần dùng khi bạn muốn các tab mã ngôn ngữ và một mẫu có thể tùy chỉnh, và khi Markdown cung cấp cho một trình tạo trang tĩnh như Docusaurus hoặc MkDocs.
Cài đặt nó và chạy chuyển đổi cơ bản:
npm install -g widdershins
widdershins openapi.yaml -o api-reference.md
Thêm các ngôn ngữ mẫu mã và bỏ qua tiêu đề front-matter khi bạn chuyển đầu ra đến nơi khác tự thêm tiêu đề của nó:
widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
--omitHeader openapi.yaml -o api-reference.md
Widdershins sử dụng hệ thống template, vì vậy bạn có thể ghi đè bố cục của bất kỳ phần nào thay vì chấp nhận mặc định. Điều đó làm cho nó trở thành cầu nối giữa một bản xuất thô và một trang tài liệu được xây dựng hoàn toàn thủ công. Chi phí là bạn hiện phải sở hữu một template và một bước xây dựng, điều này ổn cho một kho lưu trữ tài liệu nhưng quá mức cần thiết cho một tệp README nhanh.
Phương pháp 3: Một script tùy chỉnh khi bạn cần một bố cục chính xác
Đôi khi không có trình chuyển đổi có sẵn nào tạo ra hình dạng bạn muốn. Có thể bạn cần một tệp Markdown cho mỗi tag, hoặc một chỉ mục điểm cuối gọn gàng, hoặc các bảng lược đồ phù hợp với một hướng dẫn kiểu nội bộ. Trong trường hợp đó, hãy tự mình phân tích đặc tả và tạo mẫu đầu ra. Đặc tả chỉ là dữ liệu có cấu trúc, vì vậy công việc này ít hơn bạn nghĩ.
Một phiên bản Node tối thiểu liệt kê mọi hoạt động trông như thế này:
import { readFileSync, writeFileSync } from "node:fs";
import yaml from "js-yaml";
const spec = yaml.load(readFileSync("openapi.yaml", "utf8"));
const lines = [`# ${spec.info.title}`, "", spec.info.description ?? "", ""];
for (const [path, methods] of Object.entries(spec.paths)) {
for (const [method, op] of Object.entries(methods)) {
lines.push(`## ${method.toUpperCase()} ${path}`);
lines.push("");
lines.push(op.summary ?? "");
lines.push("");
const params = op.parameters ?? [];
if (params.length) {
lines.push("| Name | In | Required | Description |");
lines.push("| ---- | -- | -------- | ----------- |");
for (const p of params) {
lines.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.description ?? ""} |`);
}
lines.push("");
}
}
}
writeFileSync("api-reference.md", lines.join("\n"));
Đó là khoảng bốn mươi dòng để kiểm soát hoàn toàn đầu ra. Bạn quyết định các tiêu đề, cột bảng, cách chia tệp. Nhược điểm là việc bảo trì: khi phiên bản OpenAPI bạn nhắm đến thêm một tính năng, script của bạn phải học nó. Đối với một kiểu nội bộ ổn định, sự đánh đổi đó thường đáng giá. Để bao quát rộng đặc tả, hãy dựa vào một trình chuyển đổi được bảo trì thay thế. Nếu bạn đang cân nhắc xem nên tự viết script hay mua nó, bài tổng hợp về các trình tạo tài liệu API với xuất Markdown so sánh các tùy chọn được bảo trì bên cạnh nhau.
Phương pháp 4: Giữ đặc tả, tài liệu và các bài kiểm thử cùng nhau trong Apidog
Tất cả các trình chuyển đổi ở trên đều có một điểm mù. Chúng biến một đặc tả thành Markdown, và sau đó hai thứ này dần xa rời nhau. Ai đó chỉnh sửa API, quên chạy lại trình chuyển đổi, và Markdown trở nên sai lệch. Cách khắc phục là ngừng coi đặc tả là một tệp sống đơn lẻ và bắt đầu coi nó là một phần của không gian làm việc nơi tài liệu và kiểm thử được cập nhật cùng với nó.
Đó là mô hình mà Apidog sử dụng. Bạn nhập tệp openapi.yaml hiện có của mình, và Apidog đọc mọi đường dẫn, lược đồ và ví dụ vào một dự án. Từ đó, bạn nhận được tài liệu API được hiển thị, lưu trữ được tạo trực tiếp từ đặc tả đã nhập, không cần bước xây dựng riêng biệt. Quy trình nhập đầy đủ được đề cập trong bài viết cách nhập Swagger hoặc OpenAPI và tạo yêu cầu, và con đường từ đặc tả đến tài liệu tham khảo đã xuất bản trong bài viết tự động tạo tài liệu API từ OpenAPI.
Hai điều làm cho điều này khác biệt so với một trình chuyển đổi một lần.
Đầu tiên, tài liệu hỗ trợ các khối nội dung Markdown của riêng bạn. Tham chiếu điểm cuối được tạo ra từ đặc tả, và bạn thêm các nội dung Markdown viết tay xung quanh nó: một trang bắt đầu, ghi chú xác thực, mục nhật ký thay đổi. Bài viết mẹo tạo tài liệu với Apidog Markdown sẽ hướng dẫn bạn về phía tác giả. Vì vậy, bạn không phải chọn giữa tài liệu được tạo và tài liệu viết tay; bạn có cả hai ở một nơi.
Thứ hai, cùng một đặc tả đã nhập trở thành cơ sở cho các kịch bản kiểm thử. Bạn xây dựng các yêu cầu và xác nhận chống lại các điểm cuối mà đặc tả định nghĩa, sau đó chạy chúng để chứng minh API trực tiếp vẫn khớp với hợp đồng đã tạo ra tài liệu của bạn. Điều đó khép lại vòng lặp sai lệch: nếu API thay đổi và phá vỡ hợp đồng, các bài kiểm thử sẽ thất bại, và bạn biết tài liệu đã cũ trước khi người đọc biết.
Để làm theo, hãy tải xuống Apidog, nhập một đặc tả và mở tài liệu đã tạo trong cùng một dự án. Vấn đề không phải là Apidog in một tệp .md ra đĩa. Vấn đề là đặc tả, tài liệu dễ đọc của con người và các bài kiểm thử giữ cho cả hai trung thực không còn là ba tệp rời rạc nữa.
Tự động hóa: Tái tạo Markdown trong CI
Một trình chuyển đổi mà bạn chạy thủ công là một trình chuyển đổi mà bạn sẽ quên. Toàn bộ giá trị của việc tạo Markdown từ OpenAPI chỉ thể hiện khi quá trình tạo chạy tự động, sau mỗi lần thay đổi. Mô hình rất đơn giản: mỗi khi có push chạm đến đặc tả, hãy tái tạo Markdown và commit lại, hoặc xuất bản nó.
Đây là một job GitHub Actions tái tạo tài liệu tham khảo bất cứ khi nào openapi.yaml thay đổi:
name: Generate API docs
on:
push:
paths:
- "openapi.yaml"
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- name: Convert spec to Markdown
run: npx openapi-to-md openapi.yaml docs/api-reference.md
- name: Commit regenerated docs
run: |
git config user.name "docs-bot"
git config user.email "docs-bot@users.noreply.github.com"
git add docs/api-reference.md
git diff --staged --quiet || git commit -m "docs: regenerate API reference"
git push
Giờ đây, Markdown không bao giờ có thể lệch hơn một commit so với đặc tả. Ý tưởng tương tự cũng hoạt động trong GitLab CI hoặc bất kỳ runner nào với Node hoặc Python; hãy thay thế bước chuyển đổi bằng widdershins hoặc script của bạn.
Có một phần nữa đáng được kết nối. Tài liệu được tái tạo chỉ đáng tin cậy nếu đặc tả mà chúng đến từ đó vẫn chính xác. Đó là lúc một lần chạy kiểm thử dòng lệnh chiếm vị trí của nó trong cùng một pipeline. Apidog CLI chạy các kịch bản kiểm thử bạn đã xây dựng dựa trên đặc tả đã nhập của mình, không có giao diện người dùng, chỉ với một lệnh duy nhất:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Nó sẽ thoát với mã lỗi khác 0 nếu bất kỳ xác nhận nào thất bại, điều này làm cho quá trình xây dựng thất bại, ngăn bạn xuất bản tài liệu mô tả một API không còn hoạt động theo cách đó. Toàn bộ các cờ tùy chọn nằm trong tài liệu tham khảo lệnh apidog run, và thiết lập pipeline rộng hơn trong hướng dẫn đầy đủ về Apidog CLI. Kết hợp việc tạo tài liệu với một bài kiểm thử hợp đồng và hai điều đó sẽ củng cố lẫn nhau: đặc tả tạo ra tài liệu, và bài kiểm thử chứng minh đặc tả.
Làm sạch Markdown được tạo ra
Markdown được tạo ra hiếm khi hoàn hảo ngay từ lần đầu. Một vài thói quen giúp nó dễ đọc.
- Bỏ đi phần front matter tự động tạo khi trình hiển thị mục tiêu không muốn nó. Widdershins làm điều này với
--omitHeader; đối với các công cụ khác, một lệnhsednhanh qua đầu tệp sẽ hoạt động. - Quyết định cách chia tệp. Một tệp Markdown khổng lồ là ổn cho một README. Đối với một trang tài liệu, hãy chia theo tag hoặc tài nguyên để mỗi trang ngắn gọn.
- Giữ các ví dụ thực tế. Hầu hết các trình chuyển đổi đều lấy các giá trị ví dụ trực tiếp từ đặc tả, vì vậy chất lượng tài liệu được tạo ra của bạn phụ thuộc vào chất lượng của các
examplestrong OpenAPI. Ví dụ tốt hơn vào, tài liệu tốt hơn ra. - Tái tạo, không chỉnh sửa thủ công. Khoảnh khắc bạn chỉnh sửa thủ công Markdown được tạo ra, lần chuyển đổi tiếp theo sẽ ghi đè lên bạn. Đặt nội dung viết tay vào các tệp riêng biệt và để trình tạo chỉ sở hữu phần tham chiếu.
Nếu bản thân đặc tả của bạn lộn xộn, hãy sửa nó tại nguồn. Các đặc tả sạch hơn sẽ tạo ra tài liệu sạch hơn, và bài đăng về các công cụ xác thực OpenAPI cho thấy cách kiểm tra các lỗ hổng tạo ra đầu ra xấu.
Chọn phương pháp phù hợp cho nhóm của bạn
Hãy chọn công cụ phù hợp với nơi mà Markdown cần được gửi đến và mức độ kiểm soát bạn cần.
- Bạn muốn một tài liệu tham khảo trong kho lưu trữ chỉ với một lệnh và không quá cầu kỳ về bố cục: sử dụng
openapi-to-mdhoặcopenapi-markdown. - Bạn đang xây dựng một trang tài liệu với các mẫu mã và muốn một template có thể tùy chỉnh theme: sử dụng Widdershins.
- Bạn có một hướng dẫn kiểu nội bộ mà các trình chuyển đổi không thể đáp ứng: viết một script nhỏ trên đặc tả đã được phân tích cú pháp.
- Bạn muốn tài liệu, đặc tả và các bài kiểm thử giữ chúng luôn trung thực trong một không gian làm việc, với đầu ra được lưu trữ và không cần bước xây dựng riêng biệt để giám sát: nhập đặc tả vào Apidog.
Những điều này không loại trừ lẫn nhau. Rất nhiều nhóm sử dụng Apidog làm nguồn sự thật cho đặc tả và tài liệu được lưu trữ của nó, sau đó chạy một trình chuyển đổi trong CI để đưa tài liệu tham khảo Markdown vào kho lưu trữ để đọc ngoại tuyến. Đặc tả vẫn là chuẩn mực; Markdown là một thành phẩm được suy ra mà bạn có thể tái tạo bất cứ lúc nào.
Kết luận
Chuyển đổi OpenAPI sang Markdown là một vấn đề đã được giải quyết miễn là bạn coi đặc tả là nguồn và Markdown là một tệp phái sinh. Để có một tài liệu tham khảo nhanh trong kho lưu trữ, một trình chuyển đổi một dòng như openapi-to-md sẽ thực hiện công việc. Đối với một trang tài liệu có thể tùy chỉnh theme, Widdershins cung cấp các template và tab mã. Đối với một bố cục nội bộ chính xác, một script ngắn gọn trên đặc tả đã phân tích cú pháp sẽ thắng. Và khi bạn muốn đặc tả, tài liệu được hiển thị và các bài kiểm thử giữ chúng đồng bộ cùng tồn tại, việc nhập vào Apidog sẽ loại bỏ sự sai lệch làm hỏng mọi phương pháp khác theo thời gian.
Dù bạn chọn gì, hãy tự động hóa nó. Tạo Markdown trong CI sau mỗi thay đổi đặc tả, và tài liệu mà nhóm của bạn đọc sẽ luôn khớp với API mà chúng mô tả.