آموزش مستندسازی API ها با Open API و Swagger یکی دیگر از آموزش های گروه آموزشی پرووید می باشد که در این قسمت آن را به شما معرفی می کنیم. این بسته ی آموزشی نیز یکی از دوره های آموزشی دیگر که در حوزه ی فارسی سازی آموزش های انگلیسی تنظیم شده است می باشد. عنوان این بسته ی آموزشی مستندسازی API های ASP.NET Core با Open API و Swagger است که با نام اصلی Documenting an ASP.NET Core API with OpenAPI Swagger از شرکت Pluralsightمنتشر شده است.

مستندسازی web API های ASP.NET Core با Swaggerیا OpenAPI

تکنولوژِی Swagger یا OpenAPI یک استاندارد مستقل از زبان است که برای توصیف API های REST است. در واقع Swagger هم به کامپیوتر و هم به انسان این امکان را می دهد که قابلیت های REST API را بدون دسترسی مستقیم به source code درک کنند. اهداف اصلی آن عبارتند از:

• میزان کار مورد نیاز برای اتصال سرویس های جدا شده را به حداقل برسانید.
• زمان مورد نیاز برای مستندسازی دقیق سرویس ها را کاهش دهید.

بررسی OpenApi با Swagger

پروژه Swagger در سال 2015 به ابتکار OpenAPI اهدا شد و از آن زمان به عنوان OpenAPI نامیده می شود. هر دو نام به جای یکدیگر استفاده می شوند. با این حال “OpenAPI” به مشخصات اشاره دارد و “Swagger” به گروه های open-source و تجاری از SmartBear اشاره می کند که با مشخصات OpenAPI کار می کنند. محصولات متن باز یا open-source بعدی مانند OpenAPIGenerator نیز با وجود عدم انتشار توسط SmartBear تحت نام خانوادگی Swagger قرار می گیرند.

به طور خلاصه می توان گفت:

• OpenAPI یک استاندارد است.
• Swagger ابزاری است که از مشخصات OpenAPI استفاده می کند. به عنوان مثال: OpenAPIGenerator و SwaggerUI.

استاندارد OpenAPI (openapi.json)

استاندارد OpenAPI سندی است که قابلیت های API شما را توصیف می کند. این سند بر اساس XML و attribute annotation ها در کنترلرها و مدل ها است. این بخش اصلی جریان OpenAPI است و برای هدایت ابزارهایی مانند SwaggerUI استفاده می شود. به طور پیش فرض، نام آن openapi.json است. در اینجا نمونه ای از مشخصات OpenAPI است که برای اختصار کاهش یافته است:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{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

رابط کاربری Swagger یک UI مبتنی بر وب ارائه می دهد که اطلاعات مربوط به سرویس را با استفاده از مشخصات OpenAPI ایجاد شده ارائه می دهد. درواقع Swashbuckle و NSwag شامل یک نسخه تعبیه شده از رابط کاربری Swagger هستند، به طوری که می توان آن را با استفاده از یک middleware در برنامه ASP.NET Core شما میزبانی کرد.

مستندسازی API اغلب یک کار خسته کننده و در عین حال ضروری تلقی می شود. با استفاده از OpenAPI یا Swagger که به خوبی با ASP.NET Core ادغام شده است، می توانید این کار را بر اینکار را انجام دهید. در دوره مستندسازی ASP.NET Core API با OpenAPI یا Swaggerشما می توانید API خود را مستند سازی کنید. ابتدا نحوه افزودن اسناد برای API خود و افزودن UI که امکان آزمایش API را می دهد را یاد خواهید گرفت. سپس با نحوه استفاده از ویژگی ها و قراردادها، برای بهبود مشخصات OpenAPI ایجاد شده را آشنا خواهید شد. در پایان، نحوه برخورد با احراز هویت، ورژنینگ و سفارشی سازی رابط کاربری را بررسی خواهید کرد. پس از اتمام این دوره، مهارت ها و دانش OpenAPI مورد نیاز برای مستندسازی صحیح API های ASP.NET Core را خواهید داشت.

سرفصل مطالب آموزش ویدئویی مستندسازی API ها با Open API و Swagger

فصل اول: مقدمه این دوره آموزشی

• مقدمه این دوره آموزشی

فصل دوم: شروع به کار با OpenAPI یا Swagger

• مقدمه
• پیش نیازهای این دوره آموزشی
• بررسی Framework ها و Tooling
• چرا باید برای مستندسازی API خود از Swagger یا OpenAPI استفاده کنید؟
• برطرف کردن سردرگمی مربوط به واژگان فنی
• معرفی نسخه نمایشی
• جمع بندی

فصل سوم: مستندسازی اولین API خود با OpenAPI و Swagger

• مقدمه
• آموزش عملی: نصب Swashbuckle
• آموزش عملی: بررسی مشخصات ایجاد شده OpenAPI
• آموزش عملی: اضافه کردن UI مربوط به Swagger
• آموزش عملی: بررسی کامنت های XML در Action ها
• آموزش عملی: بررسی کامنت های XML در Model Class ها
• آموزش عملی: بهبود Documentation با Data Annotation ها
• آموزش عملی: بهبود Documentation با مثال
• آموزش عملی: صرف نظر کردن ازWarning ها در زمان مناسب
• آموزش عملی: اضافه کردن اطلاعات و توضیحات API
• جمع بندی

فصل چهارم: استفاده کردن و Override کردن و Convention های مربوط به تولید OpenAPI

• مقدمه
• بررسی اهمیت ApiExplorer
• چرا تولید کردن Response Type های صحیح مهم هستند؟
• آموزش عملی: توصیف Response Type (Status Codes) با ProducesReponseType
• آموزش عملی: استفاده از تجزیه و تحلیل API برای بهبود OpenAPI Specification
• آموزش عملی: کار با Convention هایAPI
• آموزش عملی: ایجاد کردن Conventionهای سفارشی
• مقایسه Attribute ها و Convention ها
• بررسیContent Negotiation
• آموزش عملی: مشخص کردن Type مربوط به Response Body با یک اتروبیوت Produces
• آموزش عملی: تنظیم کردن Type مربوط به Response Body با استفاده از اتروبیوت Consumes
• جمع بندی

فصل پنجم: تولید کردن Specification های OpenAPI برای سناریوهای پیشرفته Output و Input

• مقدمه
• بررسی Content Negotiation با Media Type های Vendor-specific
• آموزش عملی: پشتیبانی از انواع رسانه های فروشنده خاص
• پشتیبانی OpenAPI برای تغییرات Schema بر اساس Media Type (در Output)
• آموزش عملی: پشتیبانی از تغییرات Schema بر اساس Media Type (در Output و ResolveConflictingActions)
• آموزش عملی: پشتیبانی از تغییرات Schema بر اساس Media Type (درOutput و IOperationFilter)
• پشتیبانی OpenAPI برای تغییرات Schema بر اساس Media Type (در Input)
• آموزش عملی: پشتیبانی از تغییرات Schema بر اساس Media Type (در Input)
• سناریوهای پیشرفته
• جمع بندی

فصل ششم: کارکردن با نسخه های مختلف و محفاظت کردن از Documentation

• مقدمه
• کار کردن با چندیدن استاندارد OpenAPI
• آموزش عملی: کار با چندین استاندارد OpenAPI
• نسخه بندی (Versioning) با روش درونی NET Core
• آموزش عملی: نسخه بندی API شما
• آموزش عملی: مطابقت استاندارد OpenAPI با نسخه های API
• محافظت از API شما
• آموزش عملی: محافظت از API شما
• آموزش عملی: افزودن پشتیبانی احراز هویت به استاندارد OpenAPI
• جمع بندی

فصل هفتم: بهبود Documentation با سفارشی سازی پیشرفته

• مقدمه
• غنی سازی Comment ها با Markdown
• آموزش عملی: غنی سازی Comment ها با Markdown
• آموزش عملی: سفارشی سازی اولیه UI با پیکربندی API
• پشتیبانی از Deep Linking
• آموزش عملی: پشتیبانی از Deep Linking
• برندسازی UI
• آموزش عملی: برندسازی UI با تزریق کردن CSS سفارشی
• آموزش عملی: برندسازی UI با تزریق کردن یک Index Page سفارشی
• جمع بندی