نمره دادن به OpenAPI برای ساخت SDK
خلاصهٔ کاملتر
Octri یه ابزار رایگان به اسم OpenAPI audit منتشر کرده: آدرس فایل OpenAPI (یعنی سندی که endpointها، ورودیها و خروجیهای یه API رو توصیف میکنه) رو میدی و یه نمره از ۱۰ میگیری. به گفتهٔ Octri، این همون سنجشیه که خودشون قبل از ساختن هر SDK اجرا میکنن. نیازی به حساب کاربری نیست و طبق توضیح سایت، خود سند نگه داشته نمیشه، فقط بلوک info و اینکه کدوم قانونها نمره کم کردن ذخیره میشه.
نکتهی اصلی اینه که نمره دربارهی SDK هست نه خود API. یه API میتونه خوب طراحی شده و پرکاربرد باشه ولی خودش رو طوری توصیف کنه که کلاینت تولیدشده افتضاح دربیاد. مثلاً جوابی که schema نداره به متدی تبدیل میشه که any برمیگردونه. عملیاتی که tag نداره، تو یه namespace با اسم یه تیکه از path میافته. برای همین هر قانون به جای ایراد سلیقهای، میگه دقیقاً چی تو کد تولیدی خراب میشه.
سه قانون سنگینتر از بقیهن و هر کدوم تا ۲ امتیاز میبرن، یعنی روی هم ۶ از ۱۰. اول اینکه جوابهای موفق باید schema داشته باشن (بهجز 204 و 205). دوم اینکه مدلهای مشترک باید تو components.schemas تعریف بشن و با $ref صدا زده بشن. وگرنه یه مدل که تو ۲۰ عملیات inline شده، ۲۰ تا تایپ تقریباً یکسان میسازه. سوم اینکه اسم عمومی متدها نباید با هم تداخل داشته باشن، چون وگرنه generator بیصدا یکی رو تغییر اسم میده.
بقیهی قانونها بین ۰.۵ تا ۱.۵ امتیاز دارن: هر {placeholder} تو path یه پارامتر تعریفشده داشته باشه (۱.۵)، هر عملیات operationId داشته باشه و اسمش شبیه اسم متد باشه، مثلاً getActions به جای ActionsActionsGet. همینطور توضیح برای عملیات، بدنهی درخواست و پارامترها، تعریف خطاها، tag، نبود pathهای تکراری، تعریف احراز هویت و آدرس server. کسر نمره متناسب با بخشی از API هست که درگیره، ولی هر قانونی که اصلاً فعال بشه همون اول یکپنجم وزنش رو کم میکنه.
نمرهی ۸ به بالا «قوی»، ۶ تا ۷.۹ «متوسط» و زیر ۶ «ضعیف» حساب میشه. Octri چند API معروف رو هم سنجیده: Box با ۹.۱ و Petstore و Adyen با ۸.۷ بالای جدولن، در حالی که OpenAI با ۷.۶، GitHub با ۶.۹ و Stripe با ۶.۶ تو دستهی متوسط قرار گرفتن. سندهایی با بیشتر از حدود ۳۰۰ عملیات یا ۴۰۰ مدل هم به جای کسر نمره، پیشنهاد میگیرن که کلاینت رو بر اساس tag تقسیم کنن. این صفحه در اصل معرفی محصول Octri هم هست که از همون سند، SDK تو ده زبان و MCP server میسازه.
نکات کلیدی:
- نمره از ۱۰ با ۱۴ قانون، و سه قانون سنگین روی هم ۶ امتیاز دارن
- نبود schema برای جواب موفق یعنی متدهایی که any یا unknown برمیگردونن
- مدل inline تو ۲۰ عملیات یعنی ۲۰ تایپ تقریباً یکسان تو SDK
- Stripe ۶.۶، GitHub ۶.۹، OpenAI ۷.۶ و Box ۹.۱ گرفتن
- برای ۸ قانون از ۱۴ تا، دکمهی اصلاح خودکار تو سند وجود داره
- سند ذخیره نمیشه، فقط بلوک info و قانونهای نقضشده




