OpenAPI
OpenAPI (OpenAPI Specification, OAS) — открытый стандарт машиночитаемого описания HTTP API: какие у сервиса пути и методы, какие параметры они принимают, что возвращают и как передавать ключ. Документ пишут в JSON или YAML; по нему API понимают и люди, и программы без доступа к исходному коду.
Откуда стандарт
Стандарт вырос из Swagger Specification, первая версия которой вышла в 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, описанием и схемой параметров переносится в инструмент для вызова функций или 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, эндпоинт, данные крипторынка для ИИ-агентов.
Вопросы и ответы
Swagger и OpenAPI — одно и то же?
Это один стандарт под разными именами: Swagger Specification с 2016 года развивается как OpenAPI. Версия 2.0 вышла ещё как Swagger 2.0, а начиная с 3.0 — как OpenAPI Specification.
Нужен ли SDK, если есть спецификация?
Для Genesis API — нет: все запросы — GET с одним заголовком, хватит любого HTTP-клиента. Сгенерировать клиента из спецификации стоит, если вам нужны типизированные методы.