طراحی API Specification در Postman
مدت زمان مطالعه: : 2 دقیقه
Spec Hub در Postman برای طراحی API با رویکرد API-first استفاده میشود. در Spec Hub میتوانید specificationهای OpenAPI، AsyncAPI، protobuf، GraphQL و Smithy بسازید یا specificationهای موجود را وارد کنید. ابزارهایی مثل outline view، snippetها، autocomplete، syntax checking و پیشنمایش زنده مستندات به شما کمک میکنند ساختار API را دقیقتر طراحی کنید.
فرمتهای پشتیبانیشده #
Postman در Spec Hub از این فرمتها پشتیبانی میکند:
- OpenAPI ۲.۰، ۳.۰ و ۳.۱
- AsyncAPI ۲.۰ و ۳.۰
- protobuf ۲ و protobuf ۳
- GraphQL
- Smithy 2.0
طراحی API در specification #
میتوانید specification جدید بسازید یا فایل موجود را از کامپیوتر یا repository وارد کنید و توسعه آن را در Spec Hub ادامه دهید. هنگام ویرایش، میتوانید بخشهای جدید را با snippetهای آماده اضافه کنید، از روی JSON body schema بسازید یا از autocomplete استفاده کنید. برای OpenAPI و protobuf هم میتوانید ساختار را در چند فایل و پوشه سازماندهی کنید.
Postman هنگام ساخت specification، خطاهای syntax و مشکلهای API governance را بر اساس ruleهای تیم نشان میدهد. برای OpenAPI و AsyncAPI، پیشنمایش زنده مستندات کمک میکند اثر تغییرات را همان لحظه ببینید.
در پلن Enterprise، میتوانید componentهای reusable برای OpenAPI specificationها در Component Library تیم بسازید تا استانداردهای مشترک در یک محل نگهداری شوند و اعضای تیم از componentهای منتشرشده دوباره استفاده کنند.
همکاری روی specification #
در Postman میتوانید specification را با اعضای تیم به اشتراک بگذارید، لینک آن را برای بازخورد ارسال کنید، روی آن comment بگذارید و تغییرات را با changelog دنبال کنید. همچنین با version control میتوانید specification را fork کنید و تغییرات را در fork انجام دهید.
ساخت collection از specification #
بعد از طراحی ساختار API در specification، میتوانید از آن یک Postman Collection تولید کنید. collection تولیدشده شامل folderها، requestها و نمونه responseها بر اساس specification است و برای اشتراک با تیم یا مصرفکنندگان API مناسب است.
اگر collection از OpenAPI specification تولید شده باشد، میتوانید collection و specification را با هم sync نگه دارید. با تغییر specification میتوانید collection را update کنید، و اگر در collection تولیدشده تغییر مهمی انجام شود، میتوانید specification را با آن بهروز کنید.
منبع آموزشی: Postman Docs، بازنویسی و سادهسازیشده برای کاربران فارسیزبان.
