كيفية تحويل مواصفات OpenAPI إلى وثائق Markdown نظيفة تلقائياً

ملف OpenAPI الخاص بك هو مصدر الحقيقة لواجهة برمجة التطبيقات (API) الخاصة بك. فهو يسرد كل مسار، وكل معلمة، وكل شكل استجابة. المشكلة هي أن لا أحد تقريبًا في فريقك يرغب في قراءة YAML أو JSON الخام. مهندس الواجهة الخلفية يريد مرجعًا سريعًا لنقاط النهاية في المستودع. مطور الواجهة الأمامية يريد جدولًا لحقول الطلب يمكنه مسحه ضوئيًا في طلب سحب. الكاتب التقني يريد شيئًا يمكنه لصقه في ويكي دون إعادة كتابة المخطط بالكامل.

Markdown هو التنسيق الذي يناسب كل هؤلاء القراء. يتم عرضه على GitHub، وفي Confluence، وفي مولدات المواقع الثابتة، وفي محرر نصوص عادي. لذا فإن المهمة المتكررة هي: أخذ ملف openapi.yaml موجود بالفعل، وتحويله إلى Markdown نظيف يفتحه البشر بالفعل. القيام بذلك يدويًا بطيء ويتغير بمجرد إضافة نقطة نهاية. القيام بذلك تلقائيًا هو الإصدار الوحيد الذي يصمد أمام دورة إصدار حقيقية.

لماذا نُنشئ Markdown من OpenAPI من الأساس

تم تصميم مستند OpenAPI للآلات. تقوم الأدوات بتحليله لإنشاء العملاء، وتشغيل اختبارات العقود، والتحقق من صحة الطلبات، وعرض الوثائق التفاعلية. هذه القابلية للقراءة بواسطة الآلة هي الهدف الأساسي، وهي تستحق الحماية. إذا كنت ترغب في تحديث معلوماتك حول الحفاظ على صحة المواصفات نفسها، فإن دليل أدوات التحقق من صحة OpenAPI يغطي فحص الكود قبل أن تقوم بإنشاء أي شيء منه.

يحل Markdown مشكلة مختلفة: التوزيع على البشر في الأماكن التي لا تشغل عارض OpenAPI. تتكرر بعض الحالات المحددة مرارًا وتكرارًا.

• مجلد README.md أو /docs في المستودع، بحيث يرى المساهم الجديد قائمة نقاط النهاية دون مغادرة قاعدة الكود.
• وصف طلب سحب يحتاج إلى إظهار ما تقبله نقطة نهاية جديدة وما ترجعه.
• صفحة Confluence أو Notion حيث يراجع الفريق الأوسع، بما في ذلك غير المهندسين، العقد.
• موقع توثيق ثابت مبني باستخدام Docusaurus، MkDocs، أو Hugo، وكلها تقبل Markdown كمدخل.

الكلمة المفتاحية هي تلقائيًا. ملف Markdown تكتبه مرة وتنساه سيكون خاطئًا بحلول السباق التالي. ملف Markdown الذي يتم إعادة إنشائه من المواصفات مع كل تغيير يظل صحيحًا للعقد مجانًا. هذا هو الفرق بين الوثائق التي يثق بها الناس والوثائق التي يتعلم الناس تجاهلها.

طرق التحويل، من السريع إلى المتين

لا يوجد أمر رسمي واحد يأتي مع OpenAPI لإنتاج Markdown. بدلاً من ذلك، يوجد نظام بيئي صغير من المحولات بالإضافة إلى محركات التوثيق المضمنة في منصات واجهة برمجة التطبيقات. إليك المشهد العام، مرتبًا تقريبًا حسب مقدار الإعداد الذي يستغرقه كل منها.

اختر بناءً على مقدار التحكم الذي تحتاجه ومكان وصول الناتج. توضح الأقسام التالية كيفية عمل كل منها.

الطريقة 1: محول مفتوح المصدر يعمل بسطر واحد

أسرع مسار هو محول مخصص. يغطي اثنان من المحولات المعروفة عالمي Node و Python.

لمشروع Node، يأخذ openapi-to-md مستندًا من الإصدار الثاني أو الثالث بتنسيق YAML أو JSON ويكتب ملف Markdown منظمًا. يمكنك تشغيله دون تثبيت عام:

npx openapi-to-md openapi.yaml api-reference.md

لسلسلة أدوات Python، يقوم openapi-markdown بنفس المهمة بتثبيت pip وأمر واحد:

pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md

كلاهما يقرأ المواصفات، ويتصفح كل مسار ومخطط، ويصدر ملف Markdown واحدًا مع عناوين لكل نقطة نهاية وجداول للمعلمات والاستجابات. يكون وسيطة ملف الإخراج اختيارية في بعض هذه الأدوات؛ اتركها وسيتم تعيينها افتراضيًا إلى اسم الإدخال مع امتداد .md. وهذا يكفي لمرجع مستودع يمكنك إعادة إنشائه عند الطلب.

المفاضلة مع المحولات السريعة هي التحكم في التخطيط. تحصل على هيكلها، وليس هيكلك. إذا كانت جداولها الافتراضية تتطابق مع طريقة قراءة فريقك للوثائق، فقد انتهيت في سطر واحد. إذا كنت بحاجة إلى عينات تعليمات برمجية بخمس لغات أو ترتيب قسم معين، فأنت تريد الطريقة التالية.

الطريقة 2: Widdershins لوثائق قابلة للتخصيص مع عينات تعليمات برمجية

Widdershins هي أداة Node الراسخة لتحويل ملف OpenAPI أو Swagger إلى Markdown متوافق مع Slate. إنها الأداة التي يجب اللجوء إليها عندما تريد علامات تبويب لغة الكود وقالبًا قابلاً للتخصيص، وعندما يغذي Markdown مولد موقع ثابت مثل Docusaurus أو MkDocs.

قم بتثبيته وتشغيل التحويل الأساسي:

npm install -g widdershins
widdershins openapi.yaml -o api-reference.md

أضف لغات عينات الكود وأسقط رأس المعلومات الأمامية عندما تقوم بتوجيه الإخراج إلى مكان يضيف رؤوسه الخاصة:

widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
  --omitHeader openapi.yaml -o api-reference.md

يستخدم Widdershins نظام قوالب، لذا يمكنك تجاوز تخطيط أي قسم بدلاً من قبول الإعداد الافتراضي. هذا يجعله الجسر بين تفريغ خام وموقع توثيق مبني يدويًا بالكامل. التكلفة هي أنك الآن تمتلك قالبًا وخطوة بناء، وهذا جيد لمستودع التوثيق ومبالغ فيه لملف README سريع.

الطريقة 3: سكريبت مخصص عندما تحتاج إلى تخطيط دقيق

أحيانًا لا تنتج أي من المحولات الجاهزة الشكل الذي تريده. ربما تحتاج إلى ملف Markdown واحد لكل علامة، أو فهرس نقاط نهاية مضغوط، أو جداول مخططات تتوافق مع دليل أسلوب داخلي. في هذه الحالة، قم بتحليل المواصفات بنفسك وقالب الإخراج. المواصفات هي مجرد بيانات منظمة، لذا فإن هذا أقل عملًا مما يبدو.

إصدار Node بسيط يسرد كل عملية يبدو كالتالي:

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("| الاسم | في | مطلوب | الوصف |");
      lines.push("| ---- | -- | -------- | ----------- |");
      for (const p of params) {
        lines.push(`| ${p.name} | ${p.in} | ${p.required ? "نعم" : "لا"} | ${p.description ?? ""} |`);
      }
      lines.push("");
    }
  }
}

writeFileSync("api-reference.md", lines.join("\n"));

هذا حوالي أربعين سطرًا للتحكم الكامل في الإخراج. أنت تقرر العناوين، أعمدة الجدول، تقسيم الملف. الجانب السلبي هو الصيانة: عندما تضيف نسخة OpenAPI التي تستهدفها ميزة، يجب أن يتعلمها السكريبت الخاص بك. لنمط داخلي مستقر، عادة ما تكون هذه المقايضة تستحق العناء. لتغطية واسعة للمواصفات، اعتمد على محول يتم صيانته بدلاً من ذلك. إذا كنت توازن بين كتابة سكريبت لهذا أو شرائه، فإن مجموعة مولدات وثائق واجهة برمجة التطبيقات مع تصدير Markdown تقارن الخيارات المعتنى بها جنبًا إلى جنب.

الطريقة 4: الاحتفاظ بالمواصفات والوثائق والاختبارات معًا في Apidog

تشترك المحولات المذكورة أعلاه في نقطة عمياء واحدة. فهي تحول المواصفات إلى Markdown، ثم تتباعد الاثنتان. يقوم شخص ما بتعديل واجهة برمجة التطبيقات، وينسى إعادة تشغيل المحول، ويصبح Markdown خاطئًا. الحل هو التوقف عن التعامل مع المواصفات كملف يعيش بمفرده والبدء في التعامل معها كجزء من مساحة عمل حيث يتم تحديث الوثائق والاختبارات معها.

هذا هو النموذج الذي يستخدمه Apidog. تقوم باستيراد ملف openapi.yaml الموجود لديك، ويقرأ Apidog كل مسار ومخطط ومثال في مشروع. من هناك، تحصل على وثائق API مُقدمة ومستضافة، يتم إنشاؤها مباشرة من المواصفات المستوردة، بدون خطوة بناء منفصلة. يغطي تدفق الاستيراد الكامل في كيفية استيراد Swagger أو OpenAPI وإنشاء الطلبات، والمسار من المواصفات إلى المرجع المنشور في التوليد التلقائي لوثائق API من OpenAPI.

شيئان يجعلان هذا مختلفًا عن المحول لمرة واحدة.

• أولاً، تدعم الوثائق كتل محتوى Markdown الخاصة بك. يأتي مرجع نقطة النهاية المُنشأ من المواصفات، وتقوم بوضع Markdown مكتوب يدويًا حوله: صفحة البدء، ملاحظات المصادقة، إدخالات سجل التغيير. يتناول نصائح لإنشاء وثائق باستخدام Apidog Markdown جانب التأليف هذا. لذلك أنت لا تختار بين الوثائق المُنشأة والمكتوبة؛ تحصل على كلاهما في مكان واحد.
• ثانيًا، تصبح نفس المواصفات المستوردة أساسًا لسيناريوهات الاختبار. تقوم ببناء طلبات وتأكيدات ضد نقاط النهاية التي تحددها المواصفات، ثم تشغيلها لإثبات أن واجهة برمجة التطبيقات الحية لا تزال تتطابق مع العقد الذي أنتج وثائقك. وهذا يغلق حلقة الانحراف: إذا تغيرت واجهة برمجة التطبيقات وكسرت العقد، تفشل الاختبارات، وتعرف أن الوثائق قديمة قبل أن يدركها القارئ.

للمتابعة، قم بتنزيل Apidog، استورد مواصفات، وافتح الوثائق المُنشأة في نفس المشروع. النقطة ليست أن Apidog يطبع ملف .md على القرص. بل هي أن المواصفات، والوثائق المقروءة بشريًا، والاختبارات التي تحافظ على صدقهما تتوقف عن كونها ثلاثة ملفات منفصلة.

اجعلها تلقائية: أعد إنشاء Markdown في CI

المحول الذي تشغله يدويًا هو محول تنساه. تظهر القيمة الكاملة لتوليد Markdown من OpenAPI فقط عندما يعمل التوليد من تلقاء نفسه، مع كل تغيير. النمط بسيط: عند كل دفعة تلمس المواصفات، أعد إنشاء Markdown وقم بتثبيته مرة أخرى، أو انشره.

إليك مهمة GitHub Actions التي تعيد إنشاء المرجع كلما تغير ملف openapi.yaml:

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

الآن، لن يبتعد Markdown أبدًا بأكثر من commit واحد عن المواصفات. نفس الفكرة تعمل في GitLab CI أو أي مشغل آخر يدعم Node أو Python؛ فقط استبدل خطوة التحويل بـ widdershins أو سكريبتك الخاص.

هناك قطعة أخرى تستحق الإضافة. الوثائق التي يتم إعادة إنشائها تكون موثوقة فقط إذا كانت المواصفات التي جاءت منها لا تزال دقيقة. هنا يأتي دور تشغيل اختبار سطر الأوامر في نفس خط الأنابيب. يشغل Apidog CLI سيناريوهات الاختبار التي قمت بإنشائها ضد المواصفات المستوردة الخاصة بك، بدون واجهة رسومية، بأمر واحد:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

يخرج برمز غير صفري إذا فشل أي تأكيد، مما يؤدي إلى فشل البناء، وهذا يمنعك من نشر وثائق تصف واجهة برمجة تطبيقات لم تعد تعمل بهذه الطريقة. تتواجد تفاصيل الأعلام الكاملة في مرجع أمر تشغيل apidog، وإعداد خط الأنابيب الأوسع في الدليل الكامل لـ Apidog CLI. قم بإقران توليد الوثائق باختبار عقد، وسيعزز الاثنان بعضهما البعض: المواصفات تنتج الوثائق، والاختبار يثبت المواصفات.

تنظيف Markdown المُنشأ

نادرًا ما يكون Markdown المُنشأ مثاليًا في المرة الأولى. بعض العادات تحافظ على قابليته للقراءة.

• قم بإزالة المعلومات الأولية المُنشأة تلقائيًا عندما لا يرغب فيها العارض المستهدف. يقوم Widdershins بذلك باستخدام --omitHeader؛ بالنسبة للأدوات الأخرى، يعمل أمر sed سريع على الجزء العلوي من الملف.
• قرر تقسيم الملف. ملف Markdown واحد ضخم مناسب لملف README. لموقع وثائق، قم بالتقسيم حسب العلامة أو المورد بحيث تكون كل صفحة قصيرة.
• اجعل الأمثلة واقعية. تسحب معظم المحولات قيم الأمثلة مباشرة من المواصفات، لذا فإن جودة وثائقك المُنشأة تتبع جودة examples الخاصة بك في OpenAPI. أمثلة أفضل تؤدي إلى وثائق أفضل.
• أعد الإنشاء، لا تعدل يدويًا. بمجرد قيامك بتعديل Markdown المُنشأ يدويًا، ستتم الكتابة فوقه في التحويل التالي. ضع المحتوى المكتوب يدويًا في ملفات منفصلة ودع المولد يمتلك فقط قسم المرجع.

إذا كانت مواصفاتك نفسها فوضوية، فقم بإصلاحها من المصدر. المواصفات الأنظف تنتج وثائق أنظف، وتوضح تدوينة أدوات التحقق من صحة OpenAPI كيفية فحص الثغرات التي تنتج مخرجات غير جيدة.

اختيار الطريقة الصحيحة لفريقك

طابق الأداة مع المكان الذي يجب أن يذهب إليه Markdown ومقدار التحكم الذي تحتاجه.

• إذا كنت تريد مرجع مستودع بأمر واحد ولا تهتم بالتصميم: استخدم openapi-to-md أو openapi-markdown.
• إذا كنت تبني موقع وثائق مع أمثلة تعليمات برمجية وتريد قالبًا قابلاً للتخصيص: استخدم Widdershins.
• إذا كان لديك دليل أسلوب داخلي لا تستطيع المحولات مطابقته: اكتب سكريبتًا صغيرًا على المواصفات المحللة.
• إذا كنت تريد الوثائق والمواصفات والاختبارات التي تحافظ على صدقها في مساحة عمل واحدة، مع مخرجات مستضافة وبدون خطوة بناء منفصلة: استورد المواصفات إلى Apidog.

هذه ليست حصرية متبادلة. تستخدم العديد من الفرق Apidog كمصدر للحقيقة للمواصفات ووثائقها المستضافة، ثم تشغل محولًا في CI لوضع مرجع Markdown في المستودع للقراءة دون اتصال. تظل المواصفات أساسية؛ أما Markdown فهو ناتج مشتق يمكنك إعادة إنشائه في أي وقت.

خلاصة

يُعد تحويل OpenAPI إلى Markdown مشكلة محلولة طالما أنك تتعامل مع المواصفات كمصدر و Markdown كملف مشتق. لمرجع مستودع سريع، يقوم محول من سطر واحد مثل openapi-to-md بالمهمة. لموقع وثائق قابل للتخصيص، يمنحك Widdershins القوالب وعلامات تبويب التعليمات البرمجية. لتخطيط داخلي دقيق، يفوز سكريبت قصير على المواصفات المحللة. وعندما تريد أن تعيش المواصفات والوثائق المعروضة والاختبارات التي تحافظ على تزامنها معًا، فإن الاستيراد إلى Apidog يزيل الانحراف الذي يكسر كل نهج آخر بمرور الوقت.

مهما كان اختيارك، قم بأتمتته. قم بإنشاء Markdown في CI مع كل تغيير في المواصفات، وستتطابق الوثائق التي يقرأها فريقك دائمًا مع واجهة برمجة التطبيقات التي تصفها.