Blog

دليل ريدوكلي: كيفية استخدام Redocly CLI

Mark Ponomarev

Mark Ponomarev

9 يونيو 2025

دليل ريدوكلي: كيفية استخدام Redocly CLI

مرحباً بك في هذا الدليل الشامل حول Redocly CLI! Redocly CLI هي أداة قوية وشاملة تعمل من سطر الأوامر لتعريفات OpenAPI و Swagger. تساعدك في بناء وإدارة وفحص جودة أوصاف واجهات برمجة التطبيقات (API) الخاصة بك طوال دورة حياة واجهة برمجة التطبيقات بأكملها. سواء كنت مطورًا أو كاتبًا فنيًا أو مدير منتج لواجهات برمجة التطبيقات، فإن هذه الأداة تحتوي على شيء يناسبك.

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

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تولد وثائق API جميلة؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
button

ما هو Redocly CLI؟

كما هو مذكور في وثائقه الرسمية، فإن Redocly CLI هو "أداة OpenAPI الشاملة" الخاصة بك. يدعم OpenAPI 3.1، 3.0، 2.0 (Swagger القديم)، AsyncAPI، والمزيد. تم تصميمه لمساعدتك في:

تم بناء هذه الأداة مع الأخذ في الاعتبار الأداء وتجربة المستخدم، مما يوفر تنفيذًا سريعًا ورسائل خطأ سهلة القراءة.

لماذا تستخدم Redocly CLI؟

في عالم يعتمد على واجهات برمجة التطبيقات أولاً اليوم، يعد الحفاظ على تعريفات واجهة برمجة التطبيقات عالية الجودة أمرًا بالغ الأهمية. تساعدك Redocly CLI على تحقيق ذلك من خلال:

ماذا سيغطي هذا الدليل؟

تم تنظيم هذا الدليل لتقديم دليل خطوة بخطوة لإتقان Redocly CLI. إليك ما سنغطيه:

لنبدأ!

الفصل الأول: البدء مع Redocly CLI

سيوجهك هذا الفصل خلال الخطوات الأولى لاستخدام Redocly CLI، من التثبيت إلى تشغيل أول أمر لك.

المتطلبات الأساسية

قبل أن تبدأ، تأكد من تثبيت ما يلي على نظامك:

التثبيت

لديك عدة خيارات لتثبيت واستخدام Redocly CLI. اختر الخيار الذي يناسب احتياجاتك بشكل أفضل.

استخدام npx (موصى به للاستخدام السريع)

إذا كنت ترغب فقط في تجربة Redocly CLI دون تثبيت عام، يمكنك استخدام npx، مشغل حزم npm. سيقوم هذا الأمر بتنزيل وتشغيل أحدث إصدار من Redocly CLI.

npx @redocly/cli@latest --version

لاستخدام أي أمر redocly، ما عليك سوى إضافة npx @redocly/cli@latest في البداية. على سبيل المثال:

npx @redocly/cli@latest lint openapi.yaml

هذه طريقة رائعة لاستخدام Redocly CLI في بيئات CI/CD أو إذا كنت لا ترغب في إثقال نظامك بالحزم العامة.

التثبيت العام باستخدام npm

للاستخدام المنتظم، يعد التثبيت العام أكثر ملاءمة. يجعل الأمر redocly متاحًا مباشرة في الطرفية الخاصة بك.

npm install -g @redocly/cli@latest

بعد التثبيت، يمكنك التحقق منه عن طريق فحص الإصدار:

redocly --version

الآن يمكنك تشغيل الأوامر على هذا النحو:

redocly lint openapi.yaml

استخدام Docker

إذا كنت تفضل استخدام Docker، فإن Redocly يوفر صورة Docker مبنية مسبقًا. هذا مفيد لعزل الأداة عن بيئتك المحلية.

أولاً، اسحب الصورة من Docker Hub:

docker pull redocly/cli

لتشغيل أمر، تحتاج إلى ربط دليل العمل الحالي الخاص بك (حيث توجد ملفات API الخاصة بك) كحجم لحاوية Docker.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

في هذا الأمر، يشير $PWD إلى دليلك الحالي، والذي يتم ربطه بالدليل /spec داخل الحاوية. ستحتاج بعد ذلك إلى الإشارة إلى ملفاتك باستخدام المسار /spec.

هيكل الأمر الأساسي

الهيكل الأساسي لاستخدام Redocly CLI هو:

redocly [command] [arguments] [options]

يمكنك دائمًا الحصول على مساعدة لأمر معين باستخدام الخيار --help:

redocly lint --help

الآن بعد أن قمت بتثبيت Redocly CLI وفهمت هيكل الأمر الأساسي، دعنا ننتقل إلى استكشاف ميزاته القوية.

الفصل الثاني: الأوامر والميزات الأساسية

يغطي هذا الفصل الأوامر الأساسية لـ Redocly CLI. سنستكشف كيفية تدقيق وإدارة وتوثيق وتحليل تعريفات واجهة برمجة التطبيقات الخاصة بك. للأمثلة في هذا الفصل، سنستخدم ملف openapi.yaml بسيط.

دعنا ننشئ ملفًا باسم openapi.yaml بالمحتوى التالي:

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

القسم 2.1: تدقيق أوصاف واجهة برمجة التطبيقات الخاصة بك (lint)

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

الاستخدام الأساسي

يستخدم الأمر lint لفحص تعريف واجهة برمجة التطبيقات الخاص بك مقابل مجموعة من القواعد.

redocly lint openapi.yaml

بشكل افتراضي، يستخدم redocly lint مجموعة القواعد recommended. إذا كان ملف openapi.yaml الخاص بنا يحتوي على مشاكل، فسيتم تفصيلها في الإخراج. بالنسبة لملف المثال الخاص بنا، يجب أن يكون الإخراج كالتالي:

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

تكوين القواعد

يأتي Redocly CLI مع ثلاث مجموعات قواعد مدمجة قابلة للتكوين:

يمكنك تحديد مجموعة قواعد باستخدام الخيار --extends:

redocly lint openapi.yaml --extends=minimal

يمكنك أيضًا إنشاء مجموعات قواعد مخصصة خاصة بك في ملف تكوين redocly.yaml. سنغطي هذا في الفصل الثالث.

تنسيقات الإخراج

يدعم الأمر lint تنسيقات إخراج مختلفة باستخدام الخيار --format، وهو مفيد جدًا للتكامل مع أدوات أخرى.

مثال على استخدام تنسيق stylish:

redocly lint openapi.yaml --format=stylish

تجاهل المشكلات

في بعض الأحيان قد تحتاج إلى تجاهل مشكلة معينة. يمكنك إنشاء ملف .redocly.lint-ignore.yaml لقمع الأخطاء والتحذيرات.

redocly lint openapi.yaml --generate-ignore-file

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

القسم 2.2: إدارة أوصاف واجهة برمجة التطبيقات باستخدام bundle و split

مع نمو واجهة برمجة التطبيقات الخاصة بك، يصبح إدارة ملف OpenAPI واحد ومتجانس أمرًا مرهقًا. يوفر Redocly CLI أمرين للمساعدة في ذلك: split و bundle.

تقسيم ملف OpenAPI كبير (split)

يسمح لك الأمر split بتقسيم ملف تعريف واجهة برمجة تطبيقات كبير إلى هيكل متعدد الملفات أكثر قابلية للإدارة. يستخرج المكونات والمسارات والأمثلة إلى ملفات ومجلدات منفصلة.

دعنا نقسم ملف openapi.yaml الخاص بنا:

redocly split openapi.yaml --outDir=split-api

سيقوم هذا الأمر بإنشاء دليل split-api بالهيكل التالي:

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

سيستخدم ملف openapi.yaml الجديد في split-api الآن $ref للربط بالملفات الخارجية:

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

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

تجميع ملفات متعددة (bundle)

يقوم الأمر bundle بعكس ما يقوم به split. يأخذ ملف تعريف واجهة برمجة تطبيقات جذر ويحل جميع الروابط المحلية $ref لإنشاء ملف واحد مكتمل بذاته. هذا مفيد للأدوات التي لا تدعم تعريفات متعددة الملفات.

دعنا نجمع واجهة برمجة التطبيقات المقسمة الخاصة بنا مرة أخرى في ملف واحد:

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

سيحتوي ملف bundled-api.yaml على نفس محتوى ملف openapi.yaml الأصلي الخاص بنا.

إلغاء المراجع

يمكن للأمر bundle أيضًا إنشاء ملف تم إلغاء جميع مراجعاته بالكامل، حيث يتم حل جميع الروابط $ref (بما في ذلك الروابط البعيدة) واستبدالها بمحتواها.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

يمكن أن يكون هذا مفيدًا، ولكن كن على دراية بأنه يمكن أن يجعل الملف أكبر بكثير وأن المراجع الدائرية يمكن أن تسبب مشاكل في إخراج JSON.

القسم 2.3: إنشاء وثائق واجهة برمجة التطبيقات (build-docs)

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

الاستخدام الأساسي

لإنشاء الوثائق، استخدم الأمر build-docs:

redocly build-docs openapi.yaml

سيؤدي هذا إلى إنشاء ملف redoc-static.html في دليلك الحالي. افتحه في متصفحك لرؤية وثائقك.

يمكنك تحديد ملف إخراج مختلف باستخدام الخيار -o أو --output:

redocly build-docs openapi.yaml -o my-api-docs.html

تخصيص الإخراج

يمكنك تخصيص مظهر وثائقك باستخدام الخيار --theme.openapi. يتيح لك هذا تغيير الألوان والخطوط وحتى تعطيل أجزاء من واجهة المستخدم مثل شريط البحث.

على سبيل المثال، لتعطيل شريط البحث:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

يمكنك العثور على جميع خيارات السمات المتاحة في وثائق Redocly الرسمية.

لمزيد من التحكم، يمكنك توفير قالب Handlebars الخاص بك لعرض الوثائق. هذه ميزة متقدمة تسمح بالتخصيص الكامل لإخراج HTML.

القسم 2.4: الحصول على إحصائيات واجهة برمجة التطبيقات (stats)

يوفر الأمر stats مقاييس مفيدة حول تعريف واجهة برمجة التطبيقات الخاصة بك، مثل عدد المسارات، العمليات، المخططات، والمزيد.

كيفية الحصول على الإحصائيات

للحصول على إحصائيات لواجهة برمجة التطبيقات الخاصة بك، ما عليك سوى تشغيل:

redocly stats openapi.yaml

الإخراج الافتراضي يكون بتنسيق stylish:

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

تنسيقات مختلفة

مثل الأمر lint، يدعم stats تنسيقات إخراج مختلفة مع الخيار --format. تنسيقات json و markdown مفيدة بشكل خاص.

redocly stats openapi.yaml --format=json

هذا رائع لتغذية الإحصائيات في أدوات أو لوحات تحكم أخرى.

redocly stats openapi.yaml --format=markdown

يولد هذا جدول Markdown، وهو مثالي للتقارير أو للاستخدام في ملخصات GitHub Actions، كما سنرى في الفصل التالي.

الفصل الثالث: مواضيع متقدمة

في هذا الفصل، سنتعمق في بعض الميزات الأكثر تقدمًا في Redocly CLI، بما في ذلك ملف التكوين القوي والتكامل مع خطوط أنابيب CI/CD.

ملف التكوين (redocly.yaml)

بينما يمكنك استخدام Redocly CLI بالكامل من سطر الأوامر، فإن ملف التكوين redocly.yaml يسمح لك بتخزين تكوينك في مكان واحد، مما يجعل أوامرك أقصر وتكوينك قابلًا لإعادة الاستخدام.

دعنا ننشئ ملف redocly.yaml في جذر مشروعنا:

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

هيكل ملف التكوين

استخدام أسماء واجهة برمجة التطبيقات المستعارة

مع تكوين قسم apis، يمكنك الآن استخدام الاسم المستعار main بدلاً من مسار الملف في أوامرك:

redocly lint main
redocly stats main
redocly build-docs main

هذا مفيد بشكل خاص عندما يكون لديك واجهات برمجة تطبيقات متعددة في مشروعك. إذا قمت بتشغيل redocly lint بدون أي وسيطات، فسوف يقوم بتدقيق جميع واجهات برمجة التطبيقات المحددة في قسم apis.

التكامل المستمر (CI)

يعد دمج Redocly CLI في خط أنابيب CI/CD الخاص بك طريقة رائعة لأتمتة فحوصات جودة واجهة برمجة التطبيقات. إليك مثال على كيفية استخدامه مع GitHub Actions.

أنشئ ملفًا باسم .github/workflows/redocly.yaml:

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

يقوم سير عمل GitHub Actions هذا بما يلي:

  1. يتم تشغيله عند كل عملية دفع (push) وطلب سحب (pull request) إلى الفرع main.
  2. يقوم بسحب الكود الخاص بك (checkout).
  3. يقوم بتثبيت Node.js و Redocly CLI.
  4. يقوم بتشغيل الأمر lint بتنسيق github-actions. سيؤدي هذا تلقائيًا إلى إضافة تعليقات توضيحية لأي مشاكل مباشرة في طلبات السحب الخاصة بك.
  5. يقوم بتشغيل الأمر stats بتنسيق markdown ويلحق الإخراج بملخص المهمة، مما يمنحك تقريرًا جيدًا في كل تشغيل.

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

الفصل الرابع: مثال عملي: سير عمل كامل

في هذا الفصل الأخير، سنجمع كل ما تعلمناه ونتناول سير عمل كامل وعملي. سنقوم بما يلي:

  1. إنشاء هيكل مشروع مع تعريف واجهة برمجة تطبيقات متعددة الملفات.
  2. إنشاء ملف تكوين redocly.yaml.
  3. تدقيق تعريف واجهة برمجة التطبيقات باستخدام تكويننا المخصص.
  4. تجميع واجهة برمجة التطبيقات في ملف واحد.
  5. إنشاء وثائق واجهة برمجة التطبيقات.

1. إعداد المشروع

دعنا ننشئ دليلًا جديدًا لمشروعنا ونعد هيكل الملفات.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

الآن، دعنا ننشئ ملفات واجهة برمجة التطبيقات المقسمة.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (نقطة الدخول الرئيسية لدينا):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. إنشاء redocly.yaml

الآن، دعنا ننشئ ملف التكوين الخاص بنا في جذر دليل redocly-petstore.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

في هذا التكوين، قمنا بتعريف اسم مستعار petstore@v1 لواجهة برمجة التطبيقات الخاصة بنا وأضفنا بعض قواعد التدقيق المخصصة.

3. تدقيق واجهة برمجة التطبيقات

الآن، دعنا ندقق واجهة برمجة التطبيقات الخاصة بنا باستخدام تكويننا الجديد.

redocly lint petstore@v1

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

4. تجميع واجهة برمجة التطبيقات

بعد ذلك، دعنا نجمع واجهة برمجة التطبيقات متعددة الملفات الخاصة بنا في ملف واحد قابل للتوزيع.

redocly bundle petstore@v1 -o dist/petstore.yaml

سيؤدي هذا إلى إنشاء دليل dist يحتوي على ملف petstore.yaml بداخله، والذي يحتوي على تعريف واجهة برمجة التطبيقات الذي تم حله بالكامل.

5. إنشاء الوثائق

أخيرًا، دعنا ننشئ وثائق واجهة برمجة التطبيقات الخاصة بنا.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

سيؤدي هذا إلى إنشاء dist/petstore-docs.html. افتح هذا الملف في متصفحك لرؤية وثائق واجهة برمجة التطبيقات الجميلة والتفاعلية الخاصة بك.

وها قد انتهينا! سير عمل كامل من تعريف واجهة برمجة تطبيقات منظم ومتعدد الملفات إلى ملف مجمع ووثائق احترافية، كل ذلك يتم إدارته باستخدام Redocly CLI.

الخلاصة

في هذا الدليل، قمنا بغوص عميق في Redocly CLI. بدأنا بالأساسيات من التثبيت والأوامر الأساسية، ثم انتقلنا إلى مواضيع متقدمة مثل التكوين وتكامل CI، وأخيرًا تناولنا سير عمل كامل وعملي.

يجب أن يكون لديك الآن فهم قوي لكيفية استخدام Redocly CLI من أجل:

Redocly CLI هي أداة متعددة الاستخدامات وقوية يمكن أن تحسن بشكل كبير سير عمل تطوير واجهة برمجة التطبيقات الخاص بك. أشجعك على استكشاف ميزاتها بشكل أكبر ودمجها في مشاريعك.

موارد إضافية

شكرًا لمتابعة هذا الدليل. بناء واجهات برمجة تطبيقات سعيد!

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تولد وثائق API جميلة؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
button

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل