Swagger یک ابزار باز متن‌باز برای مستندسازی، مدیریت و بهینه‌سازی APIها است. این ابزار به توسعه‌دهندگان اجازه می‌دهد تا مستندات جامع و دقیقی از APIهای خود را تهیه کنند. APIها به‌عنوان مبانی اصلی برای ارتباط و تبادل داده بین سیستم‌ها شناخته می‌شوند و Swagger به عنوان یکی از ابزارهای محبوب در این حوزه، یک منبع پراستفاده و قابل اعتماد برای توسعه‌دهندگان فراهم می‌کند. در این مقاله، به بررسی دقیق‌تر Swagger و کاربردهای متنوع آن خواهیم پرداخت.
OpenAPI چیست و چه ارتباطی با Swagger دارد؟
OpenAPI (قبلاً به عنوان استاندارد Swagger شناخته می‌شد) یک استاندارد متن‌باز است که برای توصیف و مستندسازی APIها استفاده می‌شود. Swagger در واقع نام قدیمی برای OpenAPI بود و تا قبل از نسخه ۳.۰ از OpenAPI، از نام Swagger برای این استاندارد استفاده می‌شد.
Swagger در ابتدا توسط Tony Tam در سال ۲۰۱۰ توسعه داده شد و به عنوان یک ابزار متن‌باز برای مستندسازی و توصیف APIها شناخته می‌شد. با گذر زمان و توسعه بیشتر، Swagger تبدیل به OpenAPI شد و در حال حاضر OpenAPI به عنوان استاندارد رسمی برای توصیف APIها مورد استفاده قرار می‌گیرد.
به عبارت دیگر، Swagger یا نسخه‌های قدیمی‌تر آن، ابتدایی‌ترین نسخه از OpenAPI است. اما با توسعه و بروزرسانی‌های بعدی، نام آن به OpenAPI تغییر کرد و این نام به عنوان استاندارد رسمی برای توصیف و مستندسازی APIها شناخته می‌شود. به همین دلیل، اغلب از اصطلاحات OpenAPI و Swagger به صورت مترادف استفاده می‌شود، اما نام رسمی و استاندارد فعلی OpenAPI است.
اجزای تشکیل دهنده Swagger
Swagger به توسعه‌دهندگان اجازه می‌دهد مستندات جامع و دقیقی از APIها تهیه کنند. اجزای اصلی Swagger عبارتند از:
فایل توصیف (Swagger Specification): این فایل یک فایل متنی است که توصیف کاملی از API را شامل می‌شود. در نسخه‌های قدیمی‌تر، این فایل با پسوند .json یا .yaml ذخیره می‌شد، اما در OpenAPI، از فرمت YAML یا JSON به عنوان فرمت استاندارد استفاده می‌شود.
مسیریابی (Routing): Swagger امکان توصیف مسیرها و مسیریابی در API را فراهم می‌کند. توسعه‌دهندگان می‌توانند مسیرها، پارامترها، متدها (GET، POST، PUT، DELETE و غیره) و سایر جزئیات مربوط به مسیریابی را در فایل توصیف مشخص کنند.
پارامترها (Parameters): Swagger به توسعه‌دهندگان امکان مشخص کردن پارامترهایی که باید به عنوان ورودی درخواست ارسال شوند را می‌دهد. این پارامترها می‌توانند به صورت مسیریابی (مانند آدرس URL)، نوع (مانند رشته، عدد و غیره) و سایر خواص تعیین شوند.
مدل‌ها (Models): Swagger اجازه می‌دهد تا ساختار داده‌ها و مدل‌هایی که برای درخواست‌ها و پاسخ‌ها استفاده می‌شوند را توصیف کند. توسعه‌دهندگان می‌توانند نوع داده‌ها، فیلدها، محدودیت‌ها و روابط بین مدل‌ها را مشخص کنند.
نمونه‌های درخواست و پاسخ (Request and Response Examples): Swagger امکان ارائه نمونه‌هایی از درخواست‌ها و پاسخ‌ها را فراهم می‌کند. این نمونه‌ها می‌توانند برای نمایش نحوه استفاده از API و درک بهتر عملکرد آن مورد استفاده قرار گیرند.
امنیت (Security): Swagger امکان توصیف مسائل امنیتی مربوط به API را فراهم می‌کند. توسعه‌دهندگان می‌توانند روش‌های احراز هویت، نحوه استفاده از توکن‌ها و سایر جزئیات امنیتی را در فایل توصیف مشخص کنند.
از این اجزا و قابلیت‌ها استفاده می‌شود تا مستندات جامع و قابل استفاده از APIها را تولید کرده و توسعه‌دهندگان را در فهصل بهتر با APIها یاری دهد.
آموزش نصب Swagger در Laravel
نصب و پیکربندی Swagger در Laravel می‌تواند به توسعه‌دهندگان کمک کند تا مستندات جامعی را برای APIهای Laravel خود ایجاد کنند. در زیر مراحل نصب Swagger در Laravel را توضیح خواهم داد:
نصب پکیج
از طریق Composer، پکیج darkaonline/l5-swagger را نصب کنید. برای این کار، دستور زیر را در ترمینال اجرا کنید:
composer require darkaonline/l5-swaggerپیکربندی
برای پیکربندی Swagger در Laravel، ابتدا باید ServiceProvider و Facade مربوطه را به فایل config/app.php اضافه کنید. الف) ویرایش فایل config/app.php:
'providers' => [
// ...
\L5Swagger\L5SwaggerServiceProvider::class,
]
'aliases' => [
// ...
'L5Swagger' => \L5Swagger\Facades\L5Swagger::class,
]ب) ایجاد فایل پیکربندی:
در پوشه config/، یک فایل با نام l5-swagger.php ایجاد کنید و محتویات زیر را در آن قرار دهید:
[
/*
|--------------------------------------------------------------------------
| Edit to set the api's title
|--------------------------------------------------------------------------
*/
'title' => 'Laravel API',
/*
|--------------------------------------------------------------------------
| Edit to set the api's version number
|--------------------------------------------------------------------------
*/
'version' => '1.0.0',
/*
|--------------------------------------------------------------------------
| Edit to trust the proxy's ip address - needed for AWS Load Balancer
|--------------------------------------------------------------------------
*/
'proxy' => false,
/*
|--------------------------------------------------------------------------
| Edit to set the swagger scan base path
|--------------------------------------------------------------------------
*/
'base_path' => null,
/*
|--------------------------------------------------------------------------
| Edit to set additional routes
|--------------------------------------------------------------------------
*/
'additional_routes' => [
// \L5Swagger\RouteMerger::class,
],
/*
|--------------------------------------------------------------------------
| Config csrf methods exclusion
|--------------------------------------------------------------------------
|
| By default, Swagger UI doesn't allow to perform any requests from another domain than the current domain.
| To prevent any CSRF issues, you can exclude some methods from the CSRF middleware verification.
| You must keep `OPTIONS` as value to let the swagger-ui work properly
|
*/
'csrf' => [
'exclude' => ['OPTIONS'],
],
/*
|--------------------------------------------------------------------------
| Uncomment to add constants which can be used in annotations
|--------------------------------------------------------------------------
*/
// 'constants' => [
// 'L5_SWAGGER_CONST_HOST' => env('L5_SWAGGER_CONST_HOST', 'http://my-default-host.com'),
// ],
],
'routes' => [
/*
|--------------------------------------------------------------------------
| Route to access the documentation interface
|--------------------------------------------------------------------------
*/
'api' => 'api/documentation',
/*
|--------------------------------------------------------------------------
| Route to access the swagger json
|--------------------------------------------------------------------------
*/
'docs' => 'docs',
/*
|--------------------------------------------------------------------------
| Route to access api documentation in json format
|--------------------------------------------------------------------------
*/
'json' => 'api-docs.json',
/*
|--------------------------------------------------------------------------
| Uncomment to add additional swagger json routes
|--------------------------------------------------------------------------
*/
// 'jsons' => [
// 'v1' => 'api-docs-v1.json',
// 'v2' => 'api-docs-v2.json',
// ],
],
'paths' => [
/*
|--------------------------------------------------------------------------
| Absolute path to location where parsed swagger annotations will be stored
|--------------------------------------------------------------------------
*/
'annotations' => base_path('storage/app/swagger'),
/*
|--------------------------------------------------------------------------
| File name of the generated json documentation file
|--------------------------------------------------------------------------
*/
'docs' => base_path('public/docs'),
/*
|--------------------------------------------------------------------------
| Absolute paths to directory containing the swagger annotations are stored.
|--------------------------------------------------------------------------
*/
'annotations_paths' => [
base_path('app'),
],
],
/*
|--------------------------------------------------------------------------
| Uncomment to override swagger default config
|--------------------------------------------------------------------------
*/
// 'swagger-ui' => [
// 'configUrl'// => '/l5-swagger/swagger-config',
// ],
/*
|--------------------------------------------------------------------------
| Uncomment to enable swagger scan in a middleware
|--------------------------------------------------------------------------
*/
// 'middlewares' => [
// \L5Swagger\Http\Middleware\SwaggerMiddleware::class,
// ],
];تولید مستندات Swagger
پس از پیکربندی، برای تولید مستندات Swagger، باید دستور زیر را در ترمینال اجرا کنید:
php artisan l5-swagger:generateاین دستور مستندات Swagger را بر اساس توصیفات APIهای موجود در پروژه Laravel شما ایجاد خواهد کرد. پس از اجرای این دستور، مستندات Swagger در مسیر public/docs قابل دسترسی خواهند بود.
مشاهده مستندات Swagger
برای مشاهده مستندات Swagger، باید به آدرس http://your-domain.com/api/documentation در مرورگر خود مراجعه کنید (جایگزین your-domain.com با دامنه و آدرس واقعی شما شود). در این صفحه، می‌توانید APIهای موجود را مشاهده و تست کنید.
این مراحل به شما کمک می‌کند تا Swagger را در Laravel نصب و پیکربندی کنید و مستندات جامعی برای APIهای خود ایجاد کنید.
آموزش نصب Swagger در Node.js
نصب و پیکربندی Swagger در یک پروژه Node.js می‌تواند به توسعه‌دهندگان کمک کند تا مستندات جامعی را برای APIهای Node.js خود ایجاد کنند. در زیر مراحل نصب Swagger در یک پروژه Node.js را توضیح خواهم داد:
- نصب پکیج
از طریق npm، پکیجswagger-ui-expressرا نصب کنید. برای این کار، دستور زیر را در ترمینال اجرا کنید:
npm install swagger-ui-express- تنظیمات و مستندسازی
برای شروع، شما باید یک فایل JSON یا YAML برای توصیف API خود ایجاد کنید. در این مثال، ما از فرمت JSON استفاده خواهیم کرد. الف) ایجاد فایلswagger.json:
در ریشه پروژه خود، یک فایل با نامswagger.jsonایجاد کنید و محتویات زیر را در آن قرار دهید:
{
"swagger": "2.0",
"info": {
"title": "Node.js API",
"version": "1.0.0"
},
"paths": {
"/api/users": {
"get": {
"summary": "Get all users",
"responses": {
"۲۰۰": {
"description": "OK"
}
}
}
}
}
}در این مثال، یک مسیر /api/users با یک درخواست GET توصیف شده است.
ب) تنظیمات سرور:
حالا باید یک فایل JavaScript برای تنظیم سرور خود ایجاد کنید. در این مثال، ما از فرمت Express.js استفاده خواهیم کرد.
الف) نصب پکیج‌های مورد نیاز:
برای شروع، باید پکیج‌های express و swagger-ui-express را نصب کنید. برای این کار، دستور زیر را در ترمینال اجرا کنید:
npm install express swagger-ui-expressب) ایجاد فایل server.js:
در ریشه پروژه خود، یک فایل با نام server.js ایجاد کنید و محتویات زیر را در آن قرار دهید:
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// اضافه کردن مسیرهای دیگر برای API شما
app.get('/api/users', (req, res) => {
res.json([{ id: 1, name: 'John' }]);
});
const port = 3000;
app.listen(port, () => {
console.log(`Server is running on port ${port}`);
});در این مثال، ما از مسیر /api-docs برای نمایش مستندات Swagger استفاده می‌کنیم. همچنین یک مسیر /api/users برای API واقعی خود ایجاد کرده‌ایم.
- اجرای سرور
حالا می‌توانید سرور خود را اجراکنید. برای این کار، دستور زیر را در ترمینال اجرا کنید:
node server.js- دسترسی به مستندات
حالا مستندات Swagger شما به صورت آنلاین در آدرسhttp://localhost:3000/api-docsدر دسترس خواهند بود. با باز کردن این آدرس در مرورگر خود، می‌توانید مستندات خود را مشاهده کنید. در این مستندات، می‌توانید مسیرها، پارامترها، نوع‌های داده و توضیحات دیگر API خود را ببینید. با استفاده از Swagger UI، کاربران می‌توانند درخواست‌های مختلف را آزمایش کنند و جواب‌ها و پاسخ‌های API را مشاهده کنند.
این روش نصب و پیکربندی Swagger در یک پروژه Node.js است. با استفاده از Swagger، شما می‌توانید مستندات کاملی را برای APIهای خود ایجاد کنید و به توسعه‌دهندگان و کاربران خود کمک کنید تا با APIهای شما درک بهتری داشته باشند.
آموزش نصب Swagger در Django
نصب و پیکربندی Swagger در یک پروژه Django می‌تواند به توسعه‌دهندگان کمک کند تا مستندات جامعی را برای APIهای Django خود ایجاد کنند. در زیر مراحل نصب Swagger در یک پروژه Django را توضیح خواهم داد:
نصب پکیج
از طریق pip، پکیج drf-yasg را نصب کنید. برای این کار، دستور زیر را در ترمینال اجرا کنید:
pip install drf-yasgتنظیمات و مستندسازی
برای شروع، باید تنظیمات مربوط به Swagger را در پروژه Django خود ایجاد کنید. الف) ایجاد تنظیمات:
در فایل settings.py پروژه Django خود، به INSTALLED_APPS پکیج drf_yasg را اضافه کنید:
INSTALLED_APPS = [
# ...
'drf_yasg',
# ...
] تنظیمات مسیرها:
در فایل urls.py پروژه Django خود، به urlpatterns مسیرهای مربوط به Swagger را اضافه کنید:
from django.urls import path, include
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="Django API",
default_version='v1',
description="API documentation for Django",
terms_of_service="https://www.example.com/terms/",
contact=openapi.Contact(email="[email protected]"),
license=openapi.License(name="BSD License"),
),
public=True,
permission_classes=(permissions.AllowAny,),
)
urlpatterns = [
# ...
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
# ...
]در این مثال، ما دو مسیر /swagger/ و /redoc/ را برای نمایش مستندات Swagger ایجاد کرده‌ایم.
- اجرای سرور
حالا می‌توانید سرور خود را اجرا کنید. برای این کار، دستور زیر را در ترمینال اجرا کنید:
python manage.py runserver- دسترسی به مستندات
حالا مستندات Swagger شما به صورت آنلاین در آدرسhttp://localhost:8000/swagger/یاhttp://localhost:8000/redoc/در دسترس خواهند بود. با باز کردن یکی از این آدرس‌ها در مرورگر خود، می‌توانید مستندات خود را مشاهده کنید. در این مستندات، می‌توانید مسیرها، پارامترها، نوع‌های داده و توضیحات دیگر API خود را ببینید. با استفاده از Swagger UI یا ReDoc، کاربران می‌توانند درخواست‌های مختلف را آزمایش کنند و جواب‌ها و پاسخ‌های API را مشاهده کنند.
این روش نصب و پیکربندی Swagger در Django است. با اجرای این مراحل، می‌توانید مستندات جامعی را برای APIهای Django خود ایجاد کنید و با استفاده از Swagger UI یا ReDoc، مستندات را مشاهده و تست کنید.
فایل YAML در Swagger چه کاربردی دارد؟
فایل YAML (Yet Another Markup Language) در Swagger یک فرمت نوشتاری است که برای تعریف مستندات API استفاده می‌شود. این فایل به طور کلی برای توصیف ساختار و ویژگی‌های مربوط به مسیرها و عملیات (operations) در یک API استفاده می‌شود. فایل YAML در Swagger باعث می‌شود تا مستندات API به صورت خوانا و قابل فهمی توصیف شوند و توسعه‌دهندگان بتوانند به راحتی با آن‌ها کار کنند.
در فایل YAML در Swagger می‌توانید اطلاعات مختلفی را تعریف کنید که شامل موارد زیر می‌شوند:
توصیف مسیرها (Paths): شامل مسیرهای API و عملیاتی که بر روی هر مسیر انجام می‌شود. می‌توانید برای هر مسیر ورودی‌ها (input)، خروجی‌ها (output)، پارامترها، نوع‌های داده و سایر ویژگی‌های آن‌ها را تعریف کنید.
عملیات (Operations): هر عملیات مربوط به یک مسیر API است که شامل نوع درخواست (GET، POST، PUT، DELETE و غیره)، توضیحات، پارامترها، بدنه درخواست و خروجی‌ها است. با استفاده از فایل YAML می‌توانید هر عملیات را به طور جداگانه توصیف کنید.
پارامترها: می‌توانید پارامترهای مسیرها را تعریف کنید، از جمله پارامترهای مسیر (path parameters)، پارامترهای کوئری (query parameters) و پارامترهای بدنه (body parameters) که در درخواست‌ها استفاده می‌شوند.
نوع‌های داده: می‌توانید نوع‌های داده‌ای که در مسیرها و پارامترها استفاده می‌شوند را تعریف کنید. این نوع‌ها شامل اعداد، رشته‌ها، بولین‌ها، آرایه‌ها و سایر نوع‌های داده‌ای هستند.
توضیحات: می‌توانید توضیحات بیشتری در مورد مسیرها، عملیات، پارامترها و نوع‌های داده تعریف کنید. این توضیحات می‌توانند به توسعه‌دهندگان کمک کنند تا بهتر درک کنند که هر مسیر چه کاری انجام می‌دهد و چگونه مورد استفاده قرار می‌گیرد.
فایل YAML در Swagger به عنوان یک فرمت استاندارد برای توصیف API استفاده می‌شود و با استفاده از این فایل می‌توانید مستندات جامعی را برای API خدر زیر، یک نمونه ساده از یک فایل YAML در Swagger را مشاهده می‌کنید:
openapi: 3.0.0
info:
title: My API
description: This is a sample API
version: 1.0.0
paths:
/users:
get:
summary: Get all users
description: Retrieve a list of all users
responses:
'۲۰۰':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/users/{id}:
get:
summary: Get a user by ID
description: Retrieve a user by their ID
parameters:
- name: id
in: path
description: ID of the user
required: true
schema:
type: integer
responses:
'۲۰۰':
description: The requested user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: stringدر این نمونه، مسیر /users دو عملیات GET و /users/{id} یک عملیات GET دارد. هر مسیر شامل توضیحات، پارامترها، پاسخ‌ها و نوع‌های داده است. همچنین، در بخش components نوع داده User تعریف شده است که در عملیات‌های مختلف استفاده می‌شود.
استفاده از فایل YAML در Swagger به توسعه‌دهندگان این امکان را می‌دهد تا به سادگی و به صورت خوانا مستندات API خود را توصیف کنند و به دیگران ارائه دهند. در ضمن، فایل YAML می‌تواند به صورت خودکار توسط ابزارهای Swagger جهت تولید مستندات و کد زبان‌های مختلف استفاده شود.
جمع بندی:
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 را ایجاد و مدیریت کرد.
