مستندسازی یک API، مهم است. اگر این API عمومی باشد، نیاز به مستندات ویژهی آن، امری بدیهی است و اگر عمومی نباشد، باز هم باید دارای مستندات باشد؛ از این جهت که سایر توسعه دهندههای یک تیم بتوانند به سادگی از آن استفاده کنند و همچنین نیازی نباشد تا یک سؤال مشخص را بارها پاسخ داد. به علاوه عدم وجود مستندات کافی در مورد یک API سبب خواهد شد تا سایر توسعه دهندهها تصور کنند قابلیتی که مدنظرشان است هنوز پیاده سازی نشدهاست و خودشان شروع به توسعهی آن کنند که سبب اتلاف وقت و هزینه خواهد شد. با استفاده از Swagger که «سوواَگِر» تلفظ میشود و یا OpenAI میتوان این مشکل را برطرف کرد که ارائه دهندهی توضیحی استاندارد از API شما میباشد. توسط آن میتوان قابلیتهای یک API را دریافت و یا نحوهی تعامل با آنرا از طریق HTTP، بررسی کرد. چون خروجی آن استاندارد است و مبتنی بر JSON و یا YAML میباشد، ابزارهایی نیز برای آن تهیه شدهاند که برای نمونه میتوانند بر مبنای آن، یک UI را طراحی و ارائه کنند. البته این ابزارهای ثالث صرفا محدود به تولید UI مستندات مبتنی بر OpenAPI نیستند، بلکه امکان تولید کد و یا آزمونهای واحد نیز توسط آنها وجود دارد.
به OpenAPI Specification عبارت Swagger Specification نیز گفته میشود؛ اما OpenAPI عبارتی است که باید ترجیح داده شود.
OpenAPI و Swagger
تا اینجا دریافتیم که استاندارد
OpenAPI و یا Swagger، صرفا دو واژه برای انجام کاری مشابه هستند. اما در عمل Swagger تشکیل شدهاست از تعدادی ابزار سورس باز که برفراز استاندارد OpenAPI کار کرده و قابلیتهایی را ارائه میدهند؛ مانند Swagger Editor (برای تولید استاندارد)، Swagger UI (برای تولید UI مستندات)، Swagger CodeGen (برای تولید کدهای خودکار) و غیره. برای نمونه
swagger-ui را میتوانید در مخزن کد GitHub آن ملاحظه کنید.
البته این ابزارها به صورت عمومی تهیه شدهاند. به همین جهت محصور کنندههایی نیز برای آنها جهت یکپارچگی با ASP.NET Core، طراحی شدهاند؛ مانند میانافزار
Swashbuckle.AspNetCore. کار آن تولید OpenAPI Specification بر اساس ASP.NET Core 2x API شما میباشد که جزئیات انجام اینکار را به مرور بررسی خواهیم کرد. این کامپوننت به همراه یک swagger-ui جایگذاری شده (embedded) نیز میباشد که کار تهیهی یک UI خودکار را بر اساس این استاندارد میسر میکند.
البته محصورکنندههای متعددی برای ابزارهای Swagger، برای پروژههای ASP.NET Core وجود دارند که یکی دیگر از آنها
NSwag است. هرچند Swashbuckle.AspNetCore پرکاربردترین مورد تا به امروز بودهاست.
ساختار نمونه برنامهای که در این سری تکمیل خواهد شد
در اینجا ساختار برنامهی ASP.NET Core 2.2x نمونهی این سری را ملاحظه میکنید که هدف اصلی آن، ارائهی دو کنترلر Web API برای کتابها و نویسندههای آنها میباشد:
برای نمونه اگر برنامه را اجرا کنید، در مسیر https://localhost:5001/api/authors، لیست تمام نویسندگانی که به صورت اطلاعات آغازین برنامه، توسط OpenAPISwaggerDoc.DataLayer ثبت شدهاند، قابل مشاهدهاست:
و یا کتابهای نویسندهای خاص را در آدرسی مانند https://localhost:5001/api/authors/2902b665-1190-4c70-9915-b9c2d7680450/books میتوان مشاهده کرد:
کدهای کامل آغازین این نمونه برنامه را از اینجا میتوانید دریافت کنید:
OpenAPISwaggerDoc-01.zip و شامل این اجزا است:
- OpenAPISwaggerDoc.Entities: به همراه موجودیتهای نویسنده و کتاب است.
- OpenAPISwaggerDoc.DataLayer: شامل DbContext برنامه است؛ به همراه
تعدادی رکورد پیشفرض جهت آغاز بانک اطلاعاتی و چون DbContext را در یک پروژهی مجزا قرار دادهایم، نیاز به IDesignTimeDbContextFactory نیز دارد که این مورد هم در این پروژه لحاظ شدهاست.
- OpenAPISwaggerDoc.Models: شامل DTOهای برنامه است. برای نگاشت این DTOها به موجودیتها و برعکس، از AutoMapper استفاده شدهاست که کار این نگاشتها و تعریف پروفایل متناظر با آنها، در پروژهی OpenAPISwaggerDoc.Profiles صورت میگیرد.
- OpenAPISwaggerDoc.Services: کار استفادهی از لایهی OpenAPISwaggerDoc.DataLayer را جهت دسترسی به بانک اطلاعاتی و کار با موجودیتهای کتابها و نویسندگان، انجام میدهد. از این سرویسها در دو کنترلر Web API برنامه، برای دریافت اطلاعات نویسندگان و کتابهای آنها از بانک اطلاعاتی، استفاده میشود.
- OpenAPISwaggerDoc.Web: پروژهی اصلی است که دو کنترلر Web API را هاست میکند و تنظیمات اولیهی این سرویسها را در کلاس Startup انجام داده و همچنین کار اعمال خودکار Migrations را نیز در کلاس Program (بالاترین سطح برنامه) تکمیل میکند. رشتهی اتصالی این برنامه، در فایل appsettings.json تعریف شدهاست و به یک بانک اطلاعاتی
LocalDB اشاره میکند که پس از اجرای برنامه به صورت خودکار ساخته شده و مقدار دهی میشود.
در قسمت بعد، کار مستند سازی این API را شروع میکنیم.