اولین رویکرد API برای طراحی API های آرام

از

ntakashiNicolas Takashi

من عاشق این هستم صحبت کنید و در مورد سیستم های توزیع شده ، رایانش ابری ، معماری ، مهندسی سیستم و API ها بنویسید.

من مدتی است که با Restful API کار می کنم اکنون و یک کاری که من دوست دارم انجام دهم این است که در مورد API صحبت کنم.

بنابراین ، امروز من به شما نحوه ساختن API با استفاده از رویکرد API-First و طراحی اول با OpenAPI را به شما نشان خواهم داد مشخصات.

اول از همه ، اگر نمی دانید رویکرد API-First به چه معناست ، خوب است که این مقاله را متوقف کرده و پست وبلاگی را که برای Farfetchs نوشتم بررسی کنید وبلاگی که در آن همه مواردی را که برای شروع یک API با استفاده از API-First باید بدانید توضیح می دهم.

? – آماده سازی زمین

قبل از اینکه دستان خود را کثیف کنید ، بیایید زمینه را آماده کنیم و مورد استفاده را که ایجاد خواهد شد درک کنیم. مثالهایی را که در اینجا نشان داده می شود ، تولید کنید ، به برخی از موارد زیر احتیاج دارید.

  • NodeJS
  • مشخصات OpenAPI
  • ویرایشگر متن (من ‘ از VSCode استفاده خواهم کرد)
  • خط فرمان

استفاده از پرونده

تی درک آن آسان است ، اجازه دهید از برنامه Todo List استفاده کنیم ، این یک مفهوم بسیار رایج فراتر از جامعه توسعه نرم افزار است.

رد مسئولیت

< p class = "paragraf"> برای آسان خواندن از پرونده های اصلی برخی از اطلاعات را پنهان می کنم ، اما در پایان این پست ، پیوند مخزن Github را به اشتراک می گذارم ، بنابراین می توانید به محتوای کامل دسترسی پیدا کنید.

? – دستان خود را کثیف کنید

اکنون که محیط خود را با وابستگی های مورد نیاز دارید ، بیایید کمی لذت ببریم و شروع به دیدن اتفاقات کنیم. < p class = "paragraf"> اولین قدم ایجاد فایل ورودی برای مشخصات OpenAPI و افزودن برخی مطالب به این پرونده است.

openapi: 3.0 .0
اطلاعات:
عنوان: Todo برنامه API
توضیحات: Todo برنامه API.
نسخه: v1
تماس:
ایمیل: ‘[email protected]’
نام: ‘Nicolas Takashi’
مسیرها:
# … در اینجا محتوای بیشتری وجود دارد.

پرونده بالا نمایشی بسیار ساده از یک سند OpenAPI است ، فقط به منظور معرفی شما با مفهوم. < / p>

OpenAPI یک علامت توضیحی است ، اما اگر هنوز نمی دانید چگونه این کار می کند ، توصیه می کنم برای پشتیبانی از شما در مراحل طراحی مشخصات از اسناد رسمی استفاده کنید.

نوشتن اشیاath مسیر

شی P مسیر مسیرهای نسبی به هر نقطه پایانی و عملکرد آنها را نگه می دارد ، بیایید فایلی به نام task.yaml به آن اضافه کنیم که باید به این شکل باشد.

دریافت:
operationId: دریافت وظایف
خلاصه: بازگشت a paged لیست وظایف .
توضیحات: بازگشت a paged لیست از فعال وظایف
برچسب ها:
– وظایف
پارامترها:
– $ ref: ‘../../parameters/page-parameters.yaml#/components/parameters/page’
– $ ref: ‘../../parameters/page-parameters.yaml#/components/parameters/pageSize “
پاسخ ها: ‘200’ :
توضیحات: موفقیت
محتوا: برنامه / json:
طرحواره: $ ref: ‘../../schemas/pagedTask.yaml#/components/schemas/PagedTask “
پست:
operationId: create-task
خلاصه: ایجاد یک کار
توضیحات: ایجاد جدید کار
برچسب ها:
– وظایف
درخواست بدنه:
لازم است: درست است
محتوا: برنامه / json:
طرحواره: $ ref: ‘../../schemas/task.yaml#/components/schemas/Task “
پاسخ ها: ‘201’ :
توضیحات: ایجاد شد
سرصفحه ها:
مکان:
توضیحات: “مکان کار / وظایف ایجاد شده / {id}”
طرحواره:
نوع: رشته

در بالا می بینید که دو عمل اضافه شده است ، Todo List API برای ایجاد یک کار و دریافت لیست صفحه ای از وظایف.

اکنون می توانیم با اضافه کردن این عملیات ، API را قادر به حذف یک کار ، پیدا کردن یک کار خاص و به روزرسانی وظیفه ، برای انجام این کار ما باید یک فایل جدید به نام task-with-id.yaml ایجاد کنیم و محتوای زیر را اضافه کنیم.

دریافت:
operationId: get-task
خلاصه: دریافت کار توسط شناسه
توضیحات: بازگشت یک کار
برچسب ها:
– وظایف
پارامترها:
– در: مسیر
نام: شناسه
توضیحات: وظیفه شناسه
لازم است: درست است
طرحواره:
نوع: رشته
قالب : uuid
پاسخ ها: ‘200’ :
توضیحات: موفقیت
محتوا: برنامه / json:
طرحواره: $ ref: ‘../../schemas/task.yaml#/components/schemas/Task “
قرار دادن:
operationId: update-task
خلاصه: به روزرسانی یک کار
توضیحات: به روزرسانی یک کار
برچسب ها:
– وظایف
پارامترها:
– در: مسیر
نام: شناسه
توضیحات: وظیفه شناسه
لازم است: درست است
طرحواره:
نوع: رشته
قالب : uuid
درخواست بدنه:
لازم است: درست است
محتوا: برنامه / json:
طرحواره: $ ref: ‘../../schemas/task.yaml#/components/schemas/Task “
پاسخ ها: ‘202’ :
توضیحات: خیر محتوا
حذف:
operationId: delete-task
خلاصه: حذف یک کار
توضیحات: حذف کار
برچسب ها:
– وظایف
پارامترها:
– در: مسیر
نام: شناسه
توضیحات: وظیفه شناسه
لازم است: درست است
طرحواره:
نوع: رشته
قالب : uuid
پاسخ ها: ‘202’ :
توضیحات: خیر محتوای

احتمالاً می توانید تقریباً همه چیز را درک کنید همانطور که در فایل بالا توضیح داده شده است ، اما من معتقدم که نماد $ ref شایسته توضیح است.

استفاده از منابع

در توسعه نرم افزار این است برای به اشتراک گذاشتن کد بسیار معمول است ، و همین امر هنگام طراحی API اتفاق می افتد. با در نظر داشتن مشخصات OpenAPI به ما امکان استفاده مجدد از اشیا common مشترک را در سراسر سند OpenAPI می دهد. به API ، همانطور که در مثالهای بالا مشاهده می کنید.

اگر می خواهید نحوه کار با منابع را بهتر بفهمید و از کجا می توانید از آن استفاده کنید ، لطفاً به مقام رسمی نگاهی بیندازید مستندات.

نوشتن طرحواره اشیا

ما از یک م scلفه طرحواره به نام Task استفاده می کنیم ، این طرح در سراسر API برای نشان دادن استفاده می شود وظایف منابع ، این طرح مانند نمونه زیر است.

م componentsلفه ها:
طرحواره ها:
وظیفه:
نوع: شی
لازم است:
– نام
– شناسه
خصوصیات:
شناسه:
توضیحات: وظیفه بی نظیر شناسه
نوع: رشته
قالب : uuid
فقط خواندنی: درست
نام:
توضیحات: وظیفه نام
نوع: رشته
مثال: Todo سرویس

با کد بالا می توانیم از طرح وظیفه در تمام API استفاده مجدد کرده و از تکثیر کد جلوگیری کنید.

نوشتن پارامتر شی

درست مانند طرحواره ها ، ما می توانیم همین کار را با پارامترها انجام دهیم ، اگر پارامترهایی وجود داشته باشد که در API به اشتراک گذاشته شده باشد ، می توانیم به یک پرونده محلی یا راه دور مراجعه کنیم ، در اینجا دو پارامتر برای نمایش اطلاعات مربوط به صفحه و اندازه آن ایجاد خواهیم کرد که باید مانند مثال زیر باشد. < div class = "code-container" readability = "9"> م componentsلفه ها: مولفه های: صفحه: در : پرس و جو توضیحات: صفحه دلخواه نام: صفحه طرح واره: نوع: عدد صحیح قالب: int32 پیش فرض : 1 حداقل: 1 اندازه صفحه: در : پرس و جو description: مقدار مورد نظر از در هر صفحه نام: pageSize طرح واره: نوع: عدد صحیح قالب: int32 پیش فرض : 10 حداقل: 10 حداکثر: 100

نقطه ورود API نهایی

بعد از انبوهی از مثالهای جدا شده از پرونده ها ، بیایید ببینیم که همه چیز با هم چگونه است.

openapi: 3.0 .0
اطلاعات:
عنوان: Todo برنامه API
توضیحات: Todo برنامه API.
نسخه: v1
تماس:
ایمیل: ‘[email protected]’
نام: ‘Nicolas Takashi’
برچسب ها:
– نام: وظایف
مسیرها: ‘/tasks’ : $ ref: ‘./components/paths/tasks/task.yaml’ ‘/tasks/{id}’ : $ ref: ‘./components/paths/tasks/task-by-id.yaml’
م componentsلفه ها:
طرحواره ها:
وظیفه: $ ref: ‘components / schemas / task.yaml # / components / schemas / Task’
PagedTask: $ ref: ‘components/schemas/pagedTask.yaml#/components/schemas/PagedTask’

همه چیز خوب به نظر می رسد ، ما یک Todo List API طراحی شده ، با طراحی خوب دنبال کنید ، در حال حاضر اگر از من از کد ویژوال استودیو استفاده می کنید ، می توانید پسوندی را به نام Swagger View نصب کنید ، بنابراین می توانید مشخصات آن را مانند مثال زیر ارائه دهید.

همانطور که مشاهده می کنید نمای swagger عالی به نظر می رسد و هر مشتری می تواند API شما را از طریق Swagger-UI کاوش کند.

und Bundling OpenAPI Documents

قبل از شروع تعامل با اسناد OpenAPI برای پر کردن ، ایجاد سرورهای ساختگی و SDK برای مشتری های خود ، ما باید API را بسته بندی کنیم تا خواندن ماشین و با آن ارتباط برقرار کنید.

ث مفهوم تقسیم اسناد OpenAPI به بسیاری از پرونده ها و ارجاع آنها بعداً به این پرونده ها ، روشی است که در مراحل طراحی به شما کمک می کند ، از تکرار و جلوگیری از استفاده مجدد از کد جلوگیری می کند.

اما معتبر نیست سند OpenAPI و در حال حاضر ، خواهیم دید که چگونه بسیاری از اسناد را با استفاده از swagger-cli در یک بسته قرار دهید.

برای نصب swagger-cli بسیار ساده است ، فقط دستور بالا را اجرا کنید و کار تمام شد.

// با استفاده از npm
npm swagger-cli را نصب کنید // استفاده از نخ
نخ اضافه کنید swagger-cli

پس از آن ، فقط باید دستور بسته زیر را اجرا کنید.

swagger -cli bundle api.yaml -o ./bin/api.yaml -t yaml

انجام شد ، شما قبلاً API را فقط در یک فایل قرار داده اید ، اکنون می توانید این را پر کنید پرونده اطمینان حاصل کند که از هر راهنما استفاده شده است.

? – دستورالعملهای RESTFul

یک کار بسیار مهم که باید انجام شود ، هنگام طراحی API ها ، تعریف دستورالعمل ها است.

برای طراحی RESTFul API توسط انجمن نرم افزاری مجموعه ای از دستورالعمل ها ارائه شده است ، اما در بسیاری از موارد ، این دستورالعمل ها شرایط کسب و کار شما را برآورده نمی کنند و شما باید راهنمای خود را ایجاد کنید .

بسیار مهمتر از تعریف دستورالعمل ها این است که اطمینان حاصل کنید API های شما از این دستورالعمل ها پیروی می کنند ، به عنوان مثال اطمینان حاصل کنید که هر درخواست 200 پاسخ دارد.

اما ما می دانیم که بسیار دشوار است این کار را بدون استفاده از ابزاری برای کمک به ما انجام دهید ، بنابراین با در نظر گرفتن این نکته بگذارید شما را به یک دوست خوب معرفی کنم تا از شما در این کار پشتیبانی کند.

استفاده از طیفی برای تأیید OpenAPI اسناد

بررسی کنید آیا API های شما طبق دستورالعمل های پیشنهادی شرکت شما طراحی شده است ، که انجام آن به صورت دستی کار دشواری است.

بدین ترتیب می توانیم ابزاری مانند Spectral را برای کمک به ما و ایجاد فرایندی مستقل برای انجام این کار درخواست کنیم. به اسناد OpenAPI متصل شوید و قوانین زیادی برای اطمینان از دستورالعملهای رایج در صنعت نرم افزار برای توسعه RESTFul API ها دارد.

برای استفاده از طیفی بسیار ساده است ، شما فقط باید گره را نصب کنید بسته را با استفاده از دستور زیر وارد کنید.

// با استفاده از npm
npm نصب @ stoplight / طیفی // استفاده از نخ
نخ اضافه کنید @ stoplight / spectral

قبل از اجرای دستور lint و بررسی اینکه آیا API از این دستورالعمل ها برخوردار است یا خیر ، باید همانطور که قبلاً گفته شد ، API را بسته بندی کنید ، پس از آن فقط دستور زیر را اجرا کنید .

پرز طیفی ./bin/api.yaml –ignore-unknown-format

بعد از آن ، می توانید خروجی را در صورت وجود خطا یا عدم اطلاع مشاهده کنید ، مانند تصویر زیر.

” div “=” f “> div” = “f”> div “=” f = “=” image “=” f “=” f “=” f “=” f “=” f = “f =” f = “f =” image “=” f “/” f = “f =” f = “f =” f = “f =” image “=” f = “>” “=” f “/” ffa = ” >

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

علاوه بر مهمترین مزیتی که طیفی به ما می دهد ، ما همچنین می توانیم از این مزیت استفاده کنیم و این را در روند ادغام مداوم یا حتی از طریق git hook اضافه کنیم ، اطمینان حاصل کنیم که همیشه اسناد OpenAPI معتبر و مطابق با دستورالعمل ها خواهیم بود.

on نتیجه گیری

اجازه دهید اینجا در این پست متوقف شویم ، من واقعاً می خواهم درباره API-First و OpenAPI بیشتر صحبت کنم اما برای اولین پست ، اطلاعات زیادی وجود دارد که باید هضم شوند .

ایده پشت این پست فقط نشان دادن چگونگی شروع طراحی API با رویکرد API-First و OpenAPI Specification است. در پست بعدی ، ما در مورد سرورهای ساختگی و SDK صحبت خواهیم کرد ، اینکه چگونه می توانیم از OpenAPI برای بهبود روند توسعه استفاده کنیم.

امیدوارم از مطالب لذت برده باشید و لطفا هر گونه تردید یا پیشنهادی دارید به من اطلاع دهید ، نظر بنویسید ، یا مرا در توییتر یا مکان دیگری مورد اصابت قرار دهید.

مخزن Github با مثال

قبلاً در https://nicolastakashi.medium.com/restful-using-api-first-cd305e59305d