OpenAPI{ #openapi }¶

DHIS2 服务器可为其应用程序接口提供 OpenAPI 文档。 该文档是根据对实际应用程序接口的分析即时创建的。 这意味着该文件是完整的，但由于分析的局限性，可能会丢失或误报细节。 由于分析的局限性。

所有 OpenAPI 端点都支持 JSON 和 YAML 格式。 YAML 应使用 Accept 标头，即 application/x-yaml。

要获取包含服务器所有端点的单个文档，请使用

GET /api/openapi.json
GET /api/openapi.yaml

OBS！请注意，这样生成的文件有几 MB 大小。

通过在端点根路径上附加 openapi.json 或 openapi.yaml 到端点根路径即可访问特定端点的文档。 例如，要为 /users 端点生成文档，请使用

GET /api/users/openapi.json
GET /api/users/openapi.yaml

要生成带有特定根路径和/或标记的文档，可以使用 通用 /openapi 端点可与一个或多个 tag 和 path 选择器一起使用。 选择器。

GET /api/openapi/openapi.json?path=/users&path=/dataElements
GET /api/openapi/openapi.yaml?tag=system&tag=metadata

可用的标签有

• user
• data
• metadata
• ui
• analytics
• system
• messaging
• tracker
• integration
• login
• query
• management

所有生成 OpenAPI 文档的端点都支持以下可选的 请求参数：

failOnNameClash¶

设置为 true 时，两个或两个以上具有相同简单（非限定）名称的类型会被视为冲突，生成失败并显示错误。

当设置为 false（默认）时，名称冲突将通过在简单名称中添加数字来解决，以使每个名称都是唯一的。 因此，名称无法预测或稳定。根据名称将简单名称与预定的标记符文档合并将被破坏。 此选项仅作为预览功能，只能在开发过程中使用。

failOnInconsistency¶

设置为 true时，声明中的语义不一致会导致生成失败并产生错误。 通常这表示编程错误。例如，将一个字段同时声明为必填字段和默认值。

设置为 false时，语义不一致会被记录为警告，但生成仍在继续。 这样生成的文档可能在语义上自相矛盾，但在形式上是有效的。