লেখার জন্য YAML
লম্বা বিবরণ YAML ব্লক টেক্সটে বেশি পড়ার উপযোগী, আর কমেন্ট দিয়ে রিভিউয়ারদের জন্য স্পেকে টীকা দেওয়া যায়।
$ref পাথ বা রেসপন্স কোড না ভেঙে API স্পেক JSON ও YAML-এর মধ্যে রূপান্তর করুন।
আউটপুটের প্রতিটি লাইন, ডিফল্ট ফরম্যাটিংয়ে, তাতে থাকা মানের পাথের পাশে। পাথ কপি করতে একটি সারিতে ক্লিক করুন।
সম্পূর্ণভাবে আপনার ব্রাউজারে চলে: কিছুই আপলোড হয় না। স্প্যাম ও বট ঠেকাতে ন্যায্য ব্যবহারের সীমা প্রযোজ্য (প্রতি ইনপুটে 5 MB, রূপান্তরের হার সীমিত)।
হাতে রূপান্তর করা স্পেক দুটি কারণে ভাঙে: একটি # যা YAML কমেন্ট শুরু করে, আর স্ট্যাটাস কোড যা পূর্ণসংখ্যায় পরিণত হয়। দুটিই সামলানো হয়।
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} paths:
/pets/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
4XX:
description: Client error হাতে লেখা, কোট ছাড়া-তে বদলে দেখুন $ref কীভাবে null হয়ে যায় এবং ওয়াইল্ডকার্ড হোস্ট পার্স হতে ব্যর্থ হয়।
রূপান্তরের পর কেবল সিনট্যাক্স নয়, স্পেকটিই যাচাই করতে একটি লিন্টার চালান। এখানে সম্পাদনার সময়ই প্রতিটি লোকাল $ref যাচাই হয়।
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml লম্বা বিবরণ YAML ব্লক টেক্সটে বেশি পড়ার উপযোগী, আর কমেন্ট দিয়ে রিভিউয়ারদের জন্য স্পেকে টীকা দেওয়া যায়।
কোড জেনারেটর, গেটওয়ে ও SDK প্রায়ই JSON সবচেয়ে দ্রুত লোড করে, আর অনেকে স্পেকটি /openapi.json-এ সার্ভ করে।
দুটি ফরম্যাটই একই API বর্ণনা করে। যেকোনো দিকে স্বাধীনভাবে রূপান্তর করুন; স্পেকের কিছুই হারায় না।
যেখানেই JSON ও YAML একসঙ্গে আসে, তার জন্য কনভার্টার, ভ্যালিডেটর ও ধাপে ধাপে গাইড।
openapi.json পেস্ট বা আপলোড করুন এবং ডান দিকের প্যান থেকে YAML কপি করুন, অথবা openapi.yaml হিসেবে ডাউনলোড করুন। কাঠামো, $ref পয়েন্টার, উদাহরণ ও বিবরণ হুবহু থাকে।
হ্যাঁ। কনভার্টার ডকুমেন্টের কাঠামোর ওপর কাজ করে, তাই Swagger 2.0, OpenAPI 3.0 ও OpenAPI 3.1 স্পেক দুই দিকেই একইভাবে রূপান্তরিত হয়।
YAML-এ স্পেসের পরে # এলে তা কমেন্ট শুরু করে। কোট ছাড়া $ref:-এর পরের সবকিছু কমেন্ট হিসেবে গণ্য হতো এবং রেফারেন্সটি খালি থাকত। কনভার্টার এটি স্বয়ংক্রিয়ভাবে কোট করে।
OpenAPI-তে রেসপন্স কোড স্ট্রিং কী হতে হয়। YAML-এ কোটবিহীন 200 একটি পূর্ণসংখ্যা; বেশিরভাগ টুল এটি গ্রহণ করে, কিন্তু কঠোর ভ্যালিডেটর করে না। কোট করলে স্পেক সব জায়গায় বৈধ থাকে।
এডিটরের ওপরের টগল দিয়ে দিক বদলে YAML → JSON করুন, অথবা YAML থেকে JSON কনভার্টার ব্যবহার করুন। YAML-এর অ্যাঙ্করগুলো প্রসারিত হয়, কারণ JSON-এ এ ধরনের রেফারেন্স নেই।