OpenAPI-спецификации — Versola Docs
VersolaVersola/docs
До 1.00.7.1versola.kzGitHub
RUEN

OpenAPI-спецификации

Где в репозитории лежат машиночитаемые описания API Versola (auth, central, edge) и что покрывает каждый файл.

Каждый HTTP API Versola описан файлом OpenAPI 3.1, который лежит рядом с кодом в репозитории versola, ветка main. Эти файлы — контракт: откройте их в любом OpenAPI-просмотрщике или передайте генератору клиентов.

Auth: сервер OAuth 2.0 / OpenID Connect

Публичные эндпоинты сервиса auth. Один файл на группу эндпоинтов, каталог auth/open-api/.

СпецификацияЭндпоинтыПодробнее
authorize.yamlGET и POST /authorizeRFC 6749, PKCE, JAR, JARM
par.yamlPOST /parRFC 9126
token.yamlPOST /tokenRFC 6749, DPoP
introspect.yamlPOST /introspectRFC 7662
revoke.yamlPOST /revokeRFC 7009
userinfo.yamlGET и POST /userinfoOIDC Core
logout.yamlGET и POST /logoutFront-channel и back-channel logout
jwks.yamlGET /.well-known/jwks.jsonRFC 7517
metadata.yamlGET /.well-known/openid-configuration, GET /.well-known/oauth-authorization-serverRFC 8414

Эндпоинты ведут себя по-разному в зависимости от профиля безопасности тенанта: спецификации описывают оба профиля, поэтому читайте пометки про профили в каждом файле.

Central: плоскость управления

central/open-api/central.yaml описывает административный API, на котором построена консоль администратора: тенанты, клиенты, ресурсы, scope, разрешения, роли, пользователи, challenges, формы, локали, темы, JWKS, edge и системные настройки. Тот же файл отображается в браузере на странице Central API.

Edge: плоскость трафика

edge/open-api/edge.yaml описывает маршруты входа через браузер, проксирующий маршрут /resources/{resourceId}/{path}, /permissions/me и эндпоинты /native/* для мобильных приложений. Как они складываются в одну схему, см. в обзоре Edge.

Известные пробелы в спецификациях

Файлы OpenAPI местами отстают от кода. Если спецификация и наблюдаемое поведение расходятся, ошибка либо в коде, либо в спецификации: сообщите об этом в issues на GitHub.

  • В authorize.yaml нет response_mode и request.
  • В token.yaml и introspect.yaml не описаны client_assertion и аутентификация клиента по mutual TLS.
  • В introspect.yaml в ответе не указан cnf.
  • В central.yaml нет POST /configuration/clients/edge-certificate/renew, POST /configuration/jwks/generate, GET /configuration/jwks/keys и POST /users/registrations.
  • В полях info.license некоторых спецификаций указана лицензия, отличная от Versola Community License.