API কন্ট্রাক্ট চেকার

আপনি একটি base (পুরনো) এবং একটি revision (নতুন) OpenAPI 3.x স্পেসিফিকেশন পেস্ট (বা আপলোড) করেন, এবং এটি উভয়ের প্রতিটি path, parameter, request body, response, security requirement এবং schema পরীক্ষা করে, তারপর কী পরিবর্তন হয়েছে তা রিপোর্ট করে: যোগ বা মুছে ফেলা endpoint, parameter ও request-field প্রয়োজনীয়তার পরিবর্তন, সংকীর্ণ হওয়া type বা enum, হারিয়ে যাওয়া response field বা status code, security requirement পরিবর্তন, এবং allOf/oneOf/anyOf কম্পোজিশন পরিবর্তন।

যেকোনো কিছু যা একটি বিদ্যমান ক্লায়েন্টকে কাজ করা বন্ধ করে দিতে পারে: একটি মুছে ফেলা endpoint, একটি parameter বা request field যা required হয়ে গেছে, একটি মুছে ফেলা response field বা status code, একটি field যা আর response-এ নিশ্চিত নয়, অথবা একটি type/enum যা সংকীর্ণ হয়ে গেছে (OpenAPI 3.1-এর nullable type array সহ, যেমন `["string", "null"]` থেকে "null" সরিয়ে ফেলা)। নতুন endpoint, নতুন optional field, এবং নতুন response field additive এবং আলাদাভাবে safe হিসেবে দেখানো হয়।

হ্যাঁ। যোগ/মুছে ফেলা security requirement (global এবং per-operation), security scheme সংজ্ঞার পরিবর্তন (যেমন একটি API key header থেকে query parameter-এ সরে যাওয়া), নতুন deprecated operation, এবং server URL পরিবর্তন - সবই রিপোর্ট করা হয় - breaking বা safe না হয়ে informational findings হিসেবে, কারণ (oasdiff নিজে এই চেকগুলোকে যে ডিফল্ট severity দেয় তার সাথে মিলিয়ে) কোনো দিকই সর্বজনীনভাবে ঠিক বা ভুল নয়; আপনার API-এর জন্য এটি গুরুত্বপূর্ণ কিনা তা আপনি সিদ্ধান্ত নেন।

হ্যাঁ। ডিফ করার আগে `allOf` সদস্যদের resolve ও merge করা হয়, তাই একটি কম্পোজড schema-এর গভীরে যোগ করা একটি required field ধরা পড়েই। `oneOf`/`anyOf` variant সেট তুলনা করা হয় এবং একটি variant যোগ বা মুছে ফেলা হলে informational হিসেবে চিহ্নিত করা হয়, কারণ সেই নির্দিষ্ট পরিবর্তনটি breaking কিনা তা নির্ভর করে আপনার ক্লায়েন্টরা variant-গুলোর মধ্যে কীভাবে পার্থক্য করে তার উপর।

না - এটি শুধুমাত্র OpenAPI 3.x স্পেক তুলনা করে। Swagger 2.0 (পুরনো ফরম্যাট) parameter এবং body ভিন্নভাবে সাজায়, তাই একই নিয়ম প্রয়োগ করলে ভুল ফলাফল পাওয়া যাবে। একটি Swagger 2.0 ডকুমেন্ট পেস্ট করলে নীরবে ভুল ডিফ দেওয়ার বদলে একটি স্পষ্ট error তৈরি হয়।

না। পার্সিং এবং তুলনা দুটোই আপনার ব্রাউজারে চলে - আপনার স্পেক কখনো আপনার ডিভাইস ছাড়ে না, যা বেশিরভাগ অন্যান্য OpenAPI diff টুলের বিপরীত, যারা তাদের নিজস্ব সার্ভারে আপলোড প্রসেস করে এমনকি তারা যখন বলে যে তারা এটি সংরক্ষণ করে না তখনও। ফাইল আপলোড/ড্র্যাগ-অ্যান্ড-ড্রপ অপশন ব্যবহার করার সময়ও এটি সত্য: ফাইলটি স্থানীয়ভাবে পড়া হয়, কখনো ট্রান্সমিট করা হয় না।

এটি `application/json` request এবং response body তুলনা করে, যা অধিকাংশ REST API কভার করে, কিন্তু এটি অন্যান্য content type, response header, বিবরণ, বা উদাহরণ মূল্যায়ন করে না। ডকুমেন্টের বাইরে নির্দেশ করা একটি `$ref` (আলাদা ফাইল বা URL) নীরবে বাদ দেওয়ার বদলে unresolvable হিসেবে রিপোর্ট করা হয়।

দুটোই হ্যাঁ। প্রতিটি বক্স স্বাধীনভাবে JSON বা YAML গ্রহণ করে এবং আপনি কোনটি ব্যবহার করেছেন তা শনাক্ত করে, তাই আপনি একটি JSON base স্পেককে একটি YAML revision-এর সাথে তুলনা করতে পারেন বা উল্টোটাও। আপনি যেকোনো বক্সে একটি .json/.yaml/.yml ফাইল টেনে আনতেও পারেন, অথবা এর Upload file বাটন ব্যবহার করতে পারেন - ফাইলটি আপনার ব্রাউজারে পড়া হয় এবং কখনো কোথাও আপলোড করা হয় না।

এটি যেকোনো ডকুমেন্টের সাথে কাজ করে যাতে একটি "openapi": "3.x" field এবং একটি "paths" object আছে, যা 3.0 এবং 3.1 উভয়কেই কভার করে - যার মধ্যে 3.1-এর array-form `type` (যেমন `["string", "null"]`) অন্তর্ভুক্ত - এবং এটি শুধুমাত্র সেই ডকুমেন্টগুলো প্রত্যাখ্যান করে যা Swagger 2.0-এর মতো দেখায়।

Text (.txt), Markdown (.md), এবং JSON (.json) সবগুলোই সমর্থিত - আপনি ডাউনলোড করার আগে Download report-এর পাশে ফরম্যাট ড্রপডাউন থেকে একটি বেছে নিন। JSON এক্সপোর্টে findings-এর সম্পূর্ণ তালিকার পাশাপাশি per-severity সংখ্যা অন্তর্ভুক্ত থাকে, তাই প্রয়োজনে এটি অন্য স্ক্রিপ্টে (যেমন একটি CI চেক) পাইপ করা যেতে পারে।

দুটোই কাজ করে: তাৎক্ষণিক রি-রানের জন্য Compare চাপুন, বা শুধু টাইপ করতে থাকুন - একটি সংক্ষিপ্ত বিরতির পর এটি স্বয়ংক্রিয়ভাবে আবার তুলনা করে। আপনি অপেক্ষা না করেই তাৎক্ষণিকভাবে তুলনা করতে যেকোনো বক্স থেকে Ctrl+Enter (Mac-এ Cmd+Enter) চাপতেও পারেন।