معرفی
Swagger (Open API) یک ویژگی زبانی-آگنوستیک برای توصیف و مستندسازی REST API است. Swagger به ماشین و توسعه دهنده اجازه می دهد تا کار و قابلیت های ماشین را بدون دسترسی مستقیم به کد منبع پروژه درک کنند. اهداف اصلی swagger (Open API) عبارتند از:
- برای اتصال با Microservice حجم کاری را به حداقل برسانید.
- زمان مورد نیاز برای مستندسازی دقیق Microservice را کاهش دهید.
فرآیند پیاده سازی OpenAPI
دو پیاده سازی اصلی از API باز برای فناوری های Asp.net Core وجود دارد، مانند استفاده از Swashbuckle و NSwag. من هر دو را یک به یک در مقالات جداگانه مورد بحث قرار خواهم داد.
OpenAPI در مقابل Swagger
Open API به مشخصات و Swagger به خانواده محصولات منبع باز و تجاری SmartBear اشاره دارد که با مشخصات OpenAPI کار می کنند. محصولات متن باز بعدی مانند OpenAPIGenerator نیز در دسته Swagger قرار می گیرند.
به اختصار،
- OpenAPI مشخصات است
- Swagger ابزاری است که از مشخصات OpenAPI برای مثال OpenAPIGenerator و Swagger UI استفاده می کند.
مشخصات OpenAPI
مشخصات OpenAPI سندی است که قابلیت های API های ما را توصیف می کند. مشخصات باز مبتنی بر XML است و حاشیه نویسی را با کنترلر و مدل ها مشخص می کند. این بخش اصلی جریان OpenAPI است و برای هدایت ابزارهایی مانند SwaggerUI به صورت پیش فرض استفاده می شود. نام آن openapi.json است. فایل جیسون در زیر نمونه ای از مشخصات OpenAPI است.
- {
- "openapi": "3.0.4",
- "info": {
- "title": "API V3",
- "version": "v3"
- },
- "paths": {
- "/api/GetPayment": {
- "get": {
- "tags": [
- "GetPayment"
- ],
- "operationId": "ApiGetPayment",
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "text/plain": {
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/GetPayment"
- }
- }
- },
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/GetPayment"
- }
- }
- },
- "text/json": {
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/GetPayment"
- }
- }
- }
- }
- }
- }
- },
- "post": {
- …
- }
- },
- "/api/GetPayment/{id}": {
- "get": {
- …
- },
- "put": {
- …
- },
- "delete": {
- …
- }
- }
- },
- "components": {
- "schemas": {
- "ToDoItem": {
- "type": "object",
- "properties": {
- "id": {
- "type": "integer",
- "format": "int32"
- },
- "name": {
- "type": "string",
- "nullable": true
- },
- "isCompleted": {
- "type": "boolean"
- }
- },
- "additionalProperties": false
- }
- }
- }
- }
Swagger UI
Swagger UI (رابط کاربری) رابط کاربری مبتنی بر وب است که اطلاعات مربوط به میکروسرویس را با استفاده از مشخصات Open API ایجاد شده ارائه می دهد. هر دو Swashbuckle و NSwag شامل یک نسخه جاسازی شده از Swagger UI هستند تا بتوان آن را در برنامه هسته ASP.NET شما با استفاده از یک جزء میان افزار به نام وب میزبانی کرد. UI Of Swagger مانند زیر است.
![نحوه پیاده سازی Swagger در ASP.NET Core Web API](http://pezhvak24.ir/dl/codenevis/firstcode/article/how-to-implement-swagger-in-asp-net-core-web-api/Images/Picture1.png)
شکل 1.1
![نحوه پیاده سازی Swagger در ASP.NET Core Web API](http://pezhvak24.ir/dl/codenevis/firstcode/article/how-to-implement-swagger-in-asp-net-core-web-api/Images/Picture2.png)