OpenAPI Specification یا OAS چیست؟
توضیح نویسی OpenAPI یا به اختصار OAS، استانداری غیر وابسته به زبان است. در فایلی که با این استاندارد نوشته شده است تمام RESTful API های برنامه را به گونه ای شرح می دهیم که انسان و کامپیوتر بدون اینکه نیازی به خواندن کد برنامه داشته باشند یا بخواهند مستندات برنامه را داشته باشند یا ترافیک شبکه را پالایش کنند، به راحتی عملکرد برنامه و توانایی های آن را بفهمند.
اگر این فایل را به برنامه تان اضافه کنید، هرکسی که بخواهد از برنامه استفاده کند، بدون اینکه درگیر پیچیدگی های پیاده سازی برنامه بشود، می تواند به صورت ریموت با آن ارتباط برقرار کند.
در زیر بعضی از اطلاعاتی که می توانید در این فایل بنویسید را می بینید.
- آدرس /users برروی وب سایت فعال است و عملیات های GET /users و POST /users برروی این آدرس قابل استفاده است.
- هر کدام از عملیات ها روی آدرس های URL چه اطلاعات ورودی نیاز دارند و چه اطلاعاتی را در خروجی برمی گردانند.
- روش های احراز هویت به چه صورتی انجام می شود.
- اطلاعات تماس تان، شرایط استفاده از برنامه و گواهینامه ها و دیگر اطلاعات را می توانید در این فایل بنویسید.
توضیحات API ها را می توانید در فایلی با فرمت JSON یا YAML بنویسید. این فرمت ها توسط انسان و ماشین به راحتی خوانده و فهمیده می شود. هر اطلاعاتی که درباره ی توضیح نویسی OpenAPI بخواهید را می توانید در گیت هاب آن بخوانید.
Swagger چیست؟
Swagger یک سری برنامه ها و ابزارهای Open-source است که بر مبنای استاندارد توضیح نویسی OpenAPI تولید شده است و با کمک آنها می توانید REST API های برنامه ی خودتان را طراحی کنید، آنها را بسازید، برایشان مستند های مناسب تهیه کنید و ازشان استفاده کنید.
ابزارهای اصلی Swagger عبارتند از:
- Swagger Editor : ابزاری آنلاین که با استفاده از آن می توانید برای API های خود توضیحاتی برپایه ی استاندارد OpenAPI بنویسید.
- Swagger UI : ابزاری برای تبدیل توضیحات OpenAPI به مستندی تعاملی از API های شماست.
- Swagger Codegen : براساس توضیحات OpenAPI نوشته شده کتابخانه های سمت کلاینت و تکه کدهای سمت سرور را برایتان تولید میکند.
چرا از OpenAPI استفاده کنیم؟
اصلی ترین ویژگی فوق العاده ی OpenAPI قابلیت های زیاد و کامل آن برای توضیح توانایی های API است. وقتی برای برنامه تان توضیح هایی با استاندارد OpenAPI را نوشتید، ابزارهای Swagger می توانند به روش های مختلف در توسعه ی API های برنامه تان به شما کمک کنند.
برای مثال Swagger Codegen تکه کد سرور را برای شما آماده می کند و فقط لازم است شما منطق پشت آن را پیاده سازی کنید تا API ها آماده ی استفاده باشند. یا با همین ابزار می توانید کتابخانه های کلاینتی با بیش از 40 زبان بنویسید.
یا به راحتی با Swagger UI مستندهای تعاملی برای API های خودتان بنویسید تا همکاران شما یا هرکسی که می خواهد از آن API ها بهره ببرد، به راحتی و در همان Browser عملکرد APIها را تست کنند.
بر ای کسب اطلاعات بیشتر می توانید سایت Swagger را مطالعه کنید.