پرش به محتوای اصلی

راهنمای نمایشگر و اعتبارسنج OpenAPI

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

سند OpenAPI یا Swagger قرارداد یک API است: چه مسیرهایی دارد، هر کدام چه پارامتر و بدنه‌ای می‌گیرد و چه پاسخی می‌دهد. خواندن یک فایل YAML یا JSON چندهزارخطی سخت است و یک خطای کوچک در آن ابزارهای سازنده‌ی کد و مستندات را از کار می‌اندازد. این نمایشگر سند را می‌خواند، با اسکیمای رسمی نسخه‌اش اعتبارسنجی می‌کند و همه‌ی عملیات‌ها را با پارامترها، بدنه و پاسخ‌هایشان خوانا نشان می‌دهد.

Swagger 2.0 و OpenAPI 3.0 و 3.1 پشتیبانی می‌شوند و ارجاع‌های داخلی $ref باز می‌شوند. سند فقط در مرورگر شما خوانده می‌شود و ارجاع‌های بیرونی دریافت نمی‌شوند.

گام‌به‌گام

  1. سند را بدهید

    متن JSON یا YAML را در «سند OpenAPI یا Swagger» بچسبانید یا فایل را رها کنید؛ حجم تا ۵ مگابایت.

  2. اعتبار را بررسی کنید

    نسخه خودکار تشخیص داده می‌شود و سند با اسکیمای رسمی همان نسخه سنجیده می‌شود؛ هر خطا با مسیر دقیق و توضیح فارسی نمایش داده می‌شود.

  3. عملیات‌ها را مرور کنید

    عملیات‌ها با روش و مسیر فهرست می‌شوند؛ با «جست‌وجو در عملیات» بر اساس مسیر، روش، عنوان یا برچسب فیلتر کنید و هر کدام را باز کنید تا پارامترها و پاسخ‌ها را ببینید.

  4. سرور را انتخاب کنید

    اگر سند چند سرور تعریف کرده، یکی را انتخاب کنید تا نشانی کامل هر عملیات بر پایه‌ی آن نمایش داده شود.

نمونه‌های کاربردی

  • یک سند کوچک و معتبر

    یک عملیات GET با پارامتر مسیر؛ سند با اسکیمای OpenAPI 3.1 معتبر است.

    openapi: 3.1.0
    info:
      title: Shop API
      version: "1.0"
    paths:
      /orders/{id}:
        get:
          summary: Get one order
          parameters:
            - name: id
              in: path
              required: true
              schema:
                type: integer
          responses:
            "200":
              description: OK
    

    نتیجه: OpenAPI 3.1 · معتبر · GET /orders/{id}

  • سندی که version ندارد

    بخش info در OpenAPI همیشه به version نیاز دارد.

    openapi: 3.0.3
    info:
      title: X
    paths: {}
    

    نتیجه: /info/version: ویژگی الزامی «version» وجود ندارد.

اشتباه‌های رایج

  • نوشتن نسخه به شکل عدد در YAML: version: 1.0 به عدد تبدیل می‌شود، در حالی که اسکیما رشته می‌خواهد. آن را داخل نقل‌قول بنویسید.
  • ارجاع به فایل بیرونی: این ابزار فایل‌های دیگر را دریافت نمی‌کند؛ پیش از بررسی، سند را در یک فایل جمع کنید.
  • فراموش کردن required برای پارامتر مسیر: پارامترهای in: path همیشه باید required: true داشته باشند.
  • قاطی کردن قاعده‌های Swagger 2.0 و OpenAPI 3: مثلاً definitions مال نسخه‌ی ۲ است و در نسخه‌ی ۳ جایش components/schemas است.

Swagger یا OpenAPI؟

Swagger نام نسخه‌های اول این استاندارد بود. از نسخه‌ی ۳ نام آن OpenAPI شد و ساختار کمی عوض شد: servers جای host و basePath را گرفت، بدنه‌ی درخواست به requestBody رفت و اسکیماهای مشترک در components قرار گرفتند. نسخه‌ی 3.1 هم با JSON Schema استاندارد هماهنگ شد.

پرسش‌های متداول

آیا فایل من به سرور فرستاده می‌شود؟
خیر. خواندن، اعتبارسنجی و نمایش همه در مرورگر شما انجام می‌شود و هیچ درخواستی ارسال نمی‌شود.
ارجاع‌های $ref بیرونی چه می‌شوند؟
فقط ارجاع‌های محلی (با #) باز می‌شوند. ارجاع به فایل یا نشانی بیرونی هرگز دریافت نمی‌شود و در فهرستی جدا نمایش داده می‌شود.
اعتبارسنجی بر چه پایه‌ای است؟
بر پایه‌ی اسکیمای رسمی OpenAPI Initiative برای نسخه‌ی 2.0، 3.0 و 3.1 که همراه ابزار قرار دارد؛ نسخه از فیلد swagger یا openapi تشخیص داده می‌شود.

ابزارهای مرتبط