API 文档

Jmix REST 提供自动生成的 OpenAPI 规范格式的 API 文档。

可以使用 API 文档查看、测试 API,也可以使用 PostmanSwagger 工具根据文档生成客户端代码。

默认情况下,文档接口也需要 认证 访问。如需支持匿名访问,可设置 jmix.rest.anonymous-url-patterns 应用程序属性:

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

通用 OpenAPI 文档

通用 OpenAPI 文档包含 REST API 提供的所有接口的描述。包含这些内容:

  • 认证

  • 实体 API

  • 文件 API

  • 元数据 API

  • 消息包 API

  • 用户会话 API

通用 OpenAPI 文档支持 JSONYAML 格式:

/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/1.4

项目特定的 OpenAPI 文档

任何运行的 Jmix 应用程序都会自动生成项目特定的文档。项目特定,意思是文档中不止包含 Jmix 标准的 API,还包含项目中特定的实体,例如,UserCustomerOrder 等。

项目特定的 OpenAPI 文档也支持 JSONYAML 格式:

/docs/openapiDetailed.json

JSON 版本

/docs/openapiDetailed.yaml

YAML 版本

示例:

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