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، توسعه دهندگان می‌توانند با صرفه جویی در زمان و افزایش بهره وری، تمرکز بیشتری بر روی منطق تجاری و بهبود کیفیت نرم افزار خود داشته باشند. این ابزارها و فرمت‌ها با ارائه مستندات جامع و دقیق، به بهبود همکاری بین تیم‌های توسعه و تسهیل فرآیندهای توسعه نرم افزار کمک می‌کنند.