swagger چیه و چه کاربردی داره؟

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


در اینجا یک مثال ساده برای ایجاد یک API POST با استفاده از Swagger JSDoc در Node.js آورده شده است:
ابتدا، بستههای swagger-jsdoc و swagger-ui-express را نصب کنید:

npm install swagger-jsdoc swagger-ui-express

سپس، فایلهای JSDoc را برای تعریف مشخصات Swagger API خود ایجاد کنید. در اینجا یک مثال از تعریف یک مسیر POST ساده آورده شده است:

// app.js
const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
app.use(express.json());
const swaggerOptions = {
swaggerDefinition: {
openapi: '3.0.0',
info: {
title: 'Example API',
version: '1.0.0',
description: 'A simple example API',
},
},
apis: ['./routes/*.js'], // path to the API docs
};
// Routes
/**
@swagger
/example:
post:
summary: Creates a new example.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the example.
description:
type: string
description: Description of the example.
responses:
200:
description: Example created successfully.
500:
description: Server error.
*/
app.post('/example', (req, res) => {
// Logic to handle the creation of the example
res.status(200).send('Example created successfully');
});
// Swagger setup
const swaggerDocs = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
const port = process.env.PORT || 3000;
app.listen(port, () => console.log(Server is running on port ${port}));

در این کد، ما یک مسیر POST /example تعریف کردهایم که یک نمونه جدید ایجاد میکند. مشخصات Swagger با استفاده از توضیحات JSDoc برای این مسیر تعریف شده است.

برای دسترسی به مستندات API که توسط Swagger UI ایجاد شده است، به /api-docs در مرورگر خود مراجعه کنید.

این فقط یک مثال ابتدایی است و شما میتوانید آن را برای پاسخگویی به نیازهای خاص خود توسعه دهید.