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

استاندارد OpenAPI چیست؟

قبل از پاسخ به سوال Swagger چیست؟ نیاز است که به مفهوم OpenAPI Specification (OAS) بپردازیم. با توجه به حرکت توسعه نرم افزار به سمت برنامه‌های Api Base و میکروسرویس، توسعه‌دهندگان نیاز به یک رابط استاندارد برای APIهای RESTful خود دارند. اینجاست که OpenAPI Specification مطرح می‌شود. OAS یک فرمت متن‌باز است که فایل‌های رابطی را تولید می‌کند که هم قابل خواندن توسط ماشین و هم قابل درک برای انسان هستند. این استاندارد، به شما اجازه می‌دهد که APIهای وب‌سرویس خود را با یک رابط کاربری جذاب توصیف کنید. این فایل‌ها موارد ضروری برای استفاده از API‌ها را مشخص می‌کنند، از جمله:

• توضیح چگونگی عملکرد API: چگونگی عملکرد و وظیفه API را توضیح می‌دهد.
• مقادیر درخواست (Request): انواع و نحوه ارسال مقادیر ورودی به API.
• مقادیر پاسخ (Response): مقادیر خروجی از API و نحوه توصیف آن‌ها.
• احراز هویت (Authentication): نحوه احراز هویت درخواست‌ها و توکن‌های امنیتی.
• اطلاعات بیشتر: مواردی نظیر اطلاعات تماس، شرایط استفاده و مجوزها.

استفاده از این استاندارد، به کاربران  کمک می‌کند تا با درک اصول اولیه Restful API به‌راحتی با سرویس تعامل کنند.

Swagger چیست؟

Swagger به‌عنوان یک چارچوب متن‌باز (open source) و جامع،به توسعه‌دهندگان را در مستندسازی، طراحی، تست، و بهینه‌سازی API‌ها کمک می‌کند. این مجموعه ابزار با استفاده از فایل‌های JSON یا YAML طراحی و نوشته می‌شوند تا API‌ها را به‌طور کاملاً استاندارد و قابل فهم توصیف کنند. به‌گونه‌ای که برای توسعه‌دهندگان،تیم تست محصول، به‌راحتی قابل درک باشد. مستندات تولیدشده توسط Swagger نه‌تنها API را به‌شکلی دقیق توصیف می‌کند، بلکه امکان تست و تعامل مستقیم با API را نیز فراهم می‌سازد. به این ترتیب، ساده‌سازی ارتباطات بین سرور و کلاینت ممکن می‌شود.

 اجزای اصلی Swagger

Swagger از ابزارهای متعددی تشکیل شده است که به توسعه‌دهندگان را در مستندسازی، تست، و بهینه‌سازی API‌ها کمک می‌کند. این ابزارها شامل Swagger Editor برای ویرایش و مدیریت مستندات، Swagger UI برای نمایش و تعامل با API به‌صورت بصری، Swagger Codegen برای تولید کد کلاینت و سرور، و Swagger Hub به‌عنوان یک پلتفرم همکاری تیمی است. این اجزا به توسعه‌دهندگان کمک می‌کنند تا مستندات استاندارد و تعاملی را به‌سرعت تولید و تست کنند.در ادامه هر یک از این ابزار‌ها را بررسی میکنیم:

Swagger Editor

Swagger Editor یک ویرایشگر تحت وب است که به توسعه‌دهندگان امکان می‌دهد مستندات API را به زبان OpenAPI Specification (OAS) بنویسند و مدیریت کنند. این ویرایشگر با پشتیبانی از زبان‌های JSON و YAML، به کاربران امکان می‌دهد تا به‌سرعت مستندات API خود را ایجاد، به‌روزرسانی و اصلاح کنند. علاوه بر این، قابلیت ارائه بازخورد لحظه‌ای و پیشنهادات به توسعه‌دهندگان کمک می‌کند تا در کمترین زمان ممکن مستندات خود را تصحیح و بهبود بخشند.

Swagger UI

Swagger UI یک رابط کاربری تعاملی است که به‌طور خودکار مستندات API را از فرمت OpenAPI Specification به شکل گرافیکی نمایش می‌دهد. این رابط کاربری به توسعه‌دهندگان و کاربران API اجازه می‌دهد تا به‌طور مستقیم با API تعامل کنند و درخواست‌های HTTP را به سرور ارسال کنند. به این ترتیب، تست و بررسی عملکرد API بسیار ساده و کارآمد خواهد بود.

Swagger Codegen

Swagger Codegen یک ابزار قدرتمند است که از مستندات OpenAPI Specification کدهای کلاینت و سرور تولید می‌کند. این ابزار با پشتیبانی از بیش از 40 زبان و فریمورک مختلف، به توسعه‌دهندگان اجازه می‌دهد به‌سرعت کلاینت‌ها و سرورهای خود را براساس مستندات Swagger بسازند و از هماهنگی بین مستندات و کدهای تولید شده اطمینان حاصل کنند.

چیت شیت Swagger

ما در فایل چیت شیت Swagger به بررسی نکات و موارد مهم در جهت نصب و راه اندازی و مستندات و ... این چهارچوب نرم افزاری می‌پردازیم

دانلود

Swagger Hub

Swagger Hub یک پلتفرم جامع آنلاین است که به تیم‌های توسعه‌دهنده امکان می‌دهد به‌صورت هم‌زمان روی مستندات API کار کنند. این پلتفرم با قابلیت‌های مدیریت نسخه، همکاری تیمی، و یکپارچه‌سازی با ابزارهای محبوب، کار توسعه و مستندسازی API‌ها را تسهیل می‌کند.

این اجزای اصلی، با همکاری یکدیگر به توسعه‌دهندگان کمک می‌کنند تا APIهای خود را به شکلی دقیق، تعاملی، و استاندارد توصیف کنند. این ابزارها نه تنها در ایجاد مستندات، بلکه در تست، بهینه‌سازی و تولید کدهای مرتبط نیز نقش مهمی ایفا می‌کنند و به توسعه‌دهندگان این امکان را می‌دهند تا به‌جای تمرکز بر نوشتن مستندات دستی، بر بهبود منطق کسب‌وکار خود تمرکز کنند.

نصب Swagger در فریمورک‌های محبوب

استفاده از Swagger در فریموورک‌های محبوبی مانند Laravel و Node.js و Django و... به توسعه‌دهندگان اجازه می‌دهد تا مستنداتی دقیق و تعاملی ایجاد کنند که به راحتی قابل فهم و استفاده برای دیگر توسعه‌دهندگان است. در ادامه، چگونگی نصب و پیکربندی Swagger در این دو فریمورک به صورت گام به گام توضیح داده شده است.

نصب Swagger در Laravel

در پروژه‌های PHP با فریمورک Laravel، برای مستندسازی API با Swagger، می‌توانید از کتابخانه L5-Swagger استفاده کنید. در ادامه،به مراحل نصب و پیکربندی این کتابخانه با جزییات بیشتری پرداخته ایم:

نصب L5-Swagger

از طریق Composer کتابخانه L5-Swagger را نصب کنید:

composer require "darkaonline/l5-swagger"

publish فایل کانفیگ

از دستور زیر استفاده کنید تا فایل پیکربندی publish شود:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

تنظیمات کانفیگ

به فایل config/l5-swagger.php رفته و تنظیمات لازم را بر اساس پروژه خود انجام دهید.

مشاهده مستندات Swagger

پروژه را اجرا کرده و به مسیر /api/documentation بروید تا مستندات API را مشاهده  کنید.

نصب Swagger در Node.js

در پروژه‌های Node.js با فریمورک Express، برای مستندسازی API‌ها با Swagger، کتابخانه‌های `swagger-jsdoc` و `swagger-ui-express` را نصب کنید. سپس با پیکربندی `swagger-jsdoc` و راه‌اندازی `swagger-ui-express`، مستندات API را به‌ صورت خودکار تولید و نمایش دهید. در ادامه،به مراحل نصب و پیکربندی این کتابخانه‌ها با جزییات بیشتری پرداخته ایم:

نصب کتابخانه‌ها

کتابخانه‌های swagger-jsdoc و swagger-ui-express را با npm نصب کنید:

npm install swagger-jsdoc swagger-ui-express

پیکربندی swagger-jsdoc

فایل پیکربندی را ایجاد کنید تا مستندات مورد نیاز تولید شود:

const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const swaggerOptions = {
    swaggerDefinition: {
        openapi: '3.0.0',
        info: {
            title: 'API Documentation',
            version: '1.0.0',
        },
    },
    apis: ['./routes/*.js'], // مسیر فایل‌های API
};
const swaggerDocs = swaggerJSDoc(swaggerOptions);

راه‌اندازی swagger-ui-express

 مسیر /api-docs را برای نمایش مستندات اضافه کنید:

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

برای اطلاعات بیشتر می‌توانید به مستندات رسمی swagger-jsdoc و swagger-ui-express مراجعه کنید.

[/nore]

نصب Swagger در Django

در پروژه‌های Python با فریمورک Django، برای مستندسازی API با Swagger، ابتدا کتابخانه drf-yasg را نصب کنید. سپس drf-yasg را به INSTALLED_APPS اضافه و مسیرهای مربوط به مستندات Swagger را در urls.py تنظیم نمایید.در ادامه،به مراحل نصب و پیکربندی این کتابخانه با جزییات بیشتری پرداخته ایم:

نصب drf-yasg

 با استفاده از pip کتابخانه drf-yasg را نصب کنید:

pip install drf-yasg

افزودن به INSTALLED_APPS

drf-yasg را به فهرست INSTALLED_APPS در فایل settings.py اضافه کنید.

افزودن URLها

در فایل urls.py، مسیرهای مورد نیاز برای Swagger را تنظیم کنید:

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version='v1.0',
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)
urlpatterns = [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]

مشاهده مستندات

به /swagger بروید تا مستندات API مشاهده شود.

برای اطلاعات بیشتر می‌توانید به مستندات رسمی کتابخاه drf-yasg مراجعه کنید.

[/nore]

فایل YAML در Swagger

Swagger از فرمت‌های مختلفی برای مستندسازی API استفاده می‌کند که یکی از محبوب‌ترین آن‌ها YAML است. فایل‌های YAML (YAML Ain't Markup Language) به دلیل خوانایی بالا و سادگی در نوشتار، به‌طور گسترده در پروژه‌های مختلف استفاده می‌شوند. در این بخش، به بررسی ساختار و سینتکس فایل YAML در Swagger می‌پردازیم.

نوشتن یک فایل YAML در Swagger

برای نوشتن یک فایل YAML در Swagger،باید به طور کلی موارد زیر را در نظر بگیرید:

• ساختار کلی: با تعریف نسخه OpenAPI و بخش info شروع کنید.
• تعریف سرورها: سرورهای مختلفی که API روی آن‌ها قرار دارد را تعریف کنید.
• تعریف مسیرها: مسیرهای API را با عملیات‌های مختلف و توضیحات مرتبط مشخص کنید.
• تعریف schema‌ها: ساختار داده‌ها را در بخش components تعریف کنید تا بتوانید از آن‌ها در بخش‌های مختلف استفاده کنید.

ساختار و سینتکس فایل YAML

فایل‌های YAML برای مستندسازی API با Swagger باید از استاندارد OpenAPI Specification (OAS) پیروی کنند. در ادامه، ساختار یک فایل YAML نمونه برای یک API ساده آورده شده است:

openapi: 3.0.0
info:
  title: 7Learn Api Sample
  description: API Documentation for a sample application endpoints
  version: 1.0.0
servers:
  - url: https://api.sample.com/v1
    description: Production server
  - url: https://api.staging.sample.com/v1
    description: Staging server
paths:
  /users:
    get:
      summary: Retrieve a list of users
      description: Returns a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: John Doe
                    email:
                      type: string
                      example: johndoe@example.com
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

• OpenAPI: نسخه استاندارد OpenAPI که استفاده می‌شود. در اینجا از نسخه 3.0.0 استفاده شده است.
• info: شامل اطلاعات کلی درباره API مانند عنوان، توضیحات و نسخه.
• servers: لیستی از سرورها که API در آن‌ها میزبانی می‌شود. هر سرور می‌تواند دارای URL و توضیحات باشد.
• paths: مسیرهای API که عملیات مختلف (مانند GET، POST و ...) در آن‌ها تعریف می‌شود. هر مسیر شامل اطلاعاتی مانند توضیحات، پاسخ‌ها و نوع داده‌ها است.

• components: شامل اجزای قابل استفاده مجدد مانند schema‌ها که برای تعریف ساختار داده‌ها به کار می‌روند.

  

مزایای استفاده از YAML

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

خوانایی بالا

YAML با طراحی ساده و بدون استفاده از براکت‌ها و نمادهای پیچیده، به‌راحتی قابل خواندن است. ساختار آن بر اساس فاصله‌ها سازماندهی شده و درک آن برای انسان بسیار آسان‌تر از فرمت‌های دیگر مانند XML یا JSON است. این ویژگی به توسعه‌دهندگان کمک می‌کند تا به‌سرعت مستندات را بخوانند و تغییرات لازم را اعمال کنند. در نتیجه، YAML برای مستندسازی API‌ها به یک انتخاب محبوب تبدیل شده است.

سادگی در نوشتار

ویرایش و نوشتن فایل‌های YAML به دلیل ساختار سلسله‌مراتبی خود، بسیار راحت است. این فرمت به توسعه‌دهندگان اجازه می‌دهد تا با وضوح بیشتری بر روی ساختار داده‌ها تمرکز کنند و خطاها را به سادگی شناسایی و رفع نمایند.

پشتیبانی گسترده

yamlبه دلیل قابلیت‌های خود، در بسیاری از ابزارها و فریمورک‌های توسعه نرم‌افزار پشتیبانی می‌شود. این فرمت توسط ابزارهای مدیریت پیکربندی، مستندسازی API و بسیاری از پروژه‌های متن‌باز مورد استفاده قرار گرفته است، که انعطاف‌پذیری و قابلیت استفاده آن را در محیط‌های گوناگون تایید می‌کند.

جمع‌بندی

Swagger به‌عنوان یک ابزار قدرتمند برای مستندسازی، طراحی، تست، و بهینه‌سازی API‌ها، به توسعه‌دهندگان کمک می‌کند تا API‌های خود را به صورت شفاف و استاندارد توصیف کنند. این ابزار با استفاده از فایل‌های JSON یا YAML، امکان مستندسازی خودکار و تعاملی API‌ها را فراهم می‌کند. در این مقاله، به نصب و پیکربندی Swagger در فریمورک‌های محبوب مانند Laravel , Node.js و Django پرداخته شد. با استفاده از کتابخانه‌هایی مانند L5-Swagger در Laravel و swagger-jsdoc ,swagger-ui-express در Node.js و drf-yasg در Django ، می‌توان به‌سرعت مستندات API را ایجاد و مدیریت کرد.

یکی از مزایای اصلی Swagger، استفاده از YAML به‌عنوان یک فرمت محبوب برای مستندسازی است. YAML با خوانایی بالا، سادگی در نوشتار، و پشتیبانی گسترده در ابزارها و فریمورک‌های مختلف، به توسعه‌دهندگان کمک می‌کند تا به‌راحتی مستندات API خود را ایجاد و ویرایش کنند. استفاده از استاندارد OpenAPI، موجب سازگاری و هماهنگی بیشتر در مستندسازی API‌ها شده و امکان تعامل ساده‌تر با ابزارهای مختلف را فراهم می‌کند.

در نهایت، با استفاده از Swagger و فرمت YAML، توسعه‌دهندگان می‌توانند با صرفه‌جویی در زمان و افزایش بهره‌وری، تمرکز بیشتری بر روی منطق تجاری و بهبود کیفیت نرم‌افزار خود داشته باشند. این ابزارها و فرمت‌ها با ارائه مستندات جامع و دقیق، به بهبود همکاری بین تیم‌های توسعه و تسهیل فرآیندهای توسعه نرم‌افزار کمک می‌کنند.