Документация API

Jmix REST предоставляет автоматически сгенерированную документацию API в формате спецификации OpenAPI Specification.

Вы можете использовать документацию API для визуализации, тестирования или генерации клиентского кода для REST API с помощью таких инструментов, как Postman или Swagger.

По умолчанию операции документации, описанные ниже, требуют аутентификации. Чтобы сделать их доступными без нее, установите свойство приложения jmix.rest.anonymous-url-patterns:

jmix.rest.anonymous-url-patterns = /rest/docs/*

Общая документация OpenAPI

Общая документация OpenAPI содержит описания всех операций, предоставляемых REST API. В частности, она содержит описания API для следующих частей:

  • Аутентификация

  • Entities API

  • Files API

  • Metadata API

  • Messages API

  • User Session API

Общая документация по OpenAPI доступна в форматах JSON и YAML:

/docs/openapi.json

JSON-версия общей документации.

/docs/openapi.yaml

YAML-версия общей документации.

Например:

curl -X GET http://localhost:8080/rest/docs/openapi.json \
    -H "Authorization: Bearer <access_token>"
curl -X GET http://localhost:8080/rest/docs/openapi.yaml \
    -H "Accept: application/yaml" \
    -H "Authorization: Bearer <access_token>"
Статичная версия документации доступна в Интернете по адресу https://docs.jmix.io/openapi/2.1.

Документация OpenAPI для конкретного проекта

Любое работающее приложение Jmix также автоматически генерирует документацию по конкретному проекту. "Конкретная для проекта" означает, что она содержит документацию не только о стандартных API, которые являются частью Jmix, но и о сущностях, специфичных для вашего проекта, таких как User, Customer, Order и т. д.

Документация OpenAPI для конкретного проекта доступна в форматах JSON и YAML:

/docs/openapiDetailed.json

JSON-версия документации OpenAPI для конкретного проекта.

/docs/openapiDetailed.yaml

YAML-версия документации OpenAPI для конкретного проекта.

Например:

curl -X GET http://localhost:8080/rest/docs/openapiDetailed.json \
    -H "Authorization: Bearer <access_token>"
curl -X GET http://localhost:8080/rest/docs/openapiDetailed.yaml \
    -H "Accept: application/yaml" \
    -H "Authorization: Bearer <access_token>"