API Documentation

Jmix REST provides automatically generated API documentation in the OpenAPI Specification format.

You can use the API documentation to visualize, test, or generate a client code for the REST API using tools like Postman or Swagger.

By default, the documentation endpoints described below require authentication. To make them available without authentication, set the jmix.rest.anonymous-url-patterns application property:

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

Generic OpenAPI Documentation

The generic OpenAPI documentation contains descriptions for all endpoints the REST API provides. In particular, it contains API descriptions for the following parts:

  • Authentication

  • Entities API

  • Files API

  • Metadata API

  • Messages API

  • User Session API

The Generic OpenAPI Documentation is available in JSON and YAML formats:

/docs/openapi.json

JSON version of generic documentation.

/docs/openapi.yaml

YAML version of generic documentation.

For example:

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>"
A static version of the documentation is available online at https://docs.jmix.io/openapi/1.2/

Project-specific OpenAPI Documentation

Any running Jmix application also automatically generates project-specific documentation. Project-specific means that it contains documentation not only about the standard APIs that are part of Jmix, but also about your project-specific entities, like User, Customer, Order, etc.

The project-specific OpenAPI Documentation is available in the formats JSON and YAML:

/docs/openapiDetailed.json

JSON version of project-specific OpenAPI documentation.

/docs/openapiDetailed.yaml

YAML version of project-specific OpenAPI documentation.

For example:

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>"