OpenAPI
OpenAPI (مشخصات OpenAPI، OAS) استاندارد بازی برای توصیف ماشینخوان یک API مبتنی بر HTTP است: سرویس چه مسیرها و متدهایی دارد، چه پارامترهایی میپذیرد، چه چیزی برمیگرداند و کلید چگونه ارسال میشود. سند با JSON یا YAML نوشته میشود و هم انسانها و هم برنامهها میتوانند بدون دسترسی به کد منبع، API را از روی آن بفهمند.
استاندارد از کجا آمد
این استاندارد از مشخصات Swagger پدید آمد که نخستین بار در 2011 منتشر شد. در 2015 نسخه Swagger 2.0 به OpenAPI Initiative، پروژهای باز زیر نظر Linux Foundation، اهدا شد و از 2016 این مشخصات با نام OpenAPI توسعه مییابد. نسخه 3.0 در 2017 و نسخه 3.1 در فوریه 2021 منتشر شد؛ جدیدترین خط نسخه 3.2 است (مشخصات 3.1).
سند چه چیزی را توصیف میکند
servers— آدرس پایه API؛paths— مسیرها و متدها: هر عملیاتoperationIdخودش، یکsummaryکوتاه، پارامترها همراه با محلشان (in: query، path، header) و پاسخها بر اساس کد وضعیت دارد؛components.schemas— اسکیماهای شیء (در 3.1 بر پایه JSON Schema 2020-12)؛components.securitySchemes— احراز هویت، مثلاً کلیدی در هدر:type: apiKeyوin: header.
گزیدهای کوتاه از مشخصات Genesis API، عملیات نرخهای فاندینگ و اسکیمای کلید:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/funding/rates": {
"get": {
"operationId": "getFundingRates",
"summary": "Funding rates",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query", "required": false,
"schema": { "type": "string" } }
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": { "type": "apiKey", "in": "header",
"name": "X-API-Key" }
}
}
}
فیلدهایی که با x- شروع میشوند افزونههای مشخصاتاند: x-genesis-plans پلنهایی را فهرست میکند که عملیات را شامل میشوند.
مشخصات به چه کار میآید
از کاربردهایی که استاندارد برمیشمارد: تولید مستندات، تولید کلاینت و سرور به زبانهای مختلف و تست. برای ایجنتهای هوش مصنوعی، مشخصات یک جعبهابزار آماده است: عملیاتی با operationId، توضیح و اسکیمای پارامتر به ابزاری برای function calling یا سرور MCP تبدیل میشود.
OpenAPI در Genesis API
مشخصات Genesis API در genesisarbitrage.com/openapi.json قرار دارد: OpenAPI 3.1، با 37 عملیات و کلید در هدر X-API-Key (احراز هویت). بهصورت خودکار هم پیدا میشود: فایل /.well-known/api-catalog در genesisarbitrage.com، که در RFC 9727 تعریف شده، با لینک service-desc به آن اشاره میکند. نحوه اتصال مشخصات به یک ایجنت در Genesis API برای ایجنتهای هوش مصنوعی آمده است.
همچنین ببینید: REST API، JSON، endpoint در API، دادههای بازار ارز دیجیتال برای ایجنتهای هوش مصنوعی.
پرسش و پاسخ
آیا Swagger و OpenAPI یکی هستند؟
یک استاندارد با دو ناماند: مشخصات Swagger از 2016 با نام OpenAPI توسعه مییابد. نسخه 2.0 هنوز با نام Swagger 2.0 منتشر شد و از 3.0 به بعد با نام OpenAPI Specification منتشر میشود.
اگر مشخصات داریم، SDK لازم است؟
برای Genesis API نه: هر درخواست یک GET با یک هدر است و هر کلاینت HTTP کار میکند. تولید کلاینت از روی مشخصات وقتی معنا دارد که متدهای تایپدار بخواهید.