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 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.resource-server.anonymous-url-patterns application property:

jmix.resource-server.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/2.7

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