OpenAPI¶
Le serveur DHIS2 peut fournir un document OpenAPI pour son API. Ce document est créé à la volée à partir de l'analyse de l'API réelle. Cela signifie que le document est terminé, mais que des détails peuvent être perdus ou mal interprétés en raison des limites de l'analyse.
Les formats JSON et YAML sont supportés par tous les points d'entrée de l'OpenAPI. YAML doit être consulté avec un en-tête Accepter de application/x-yaml.
Pour récupérer un document unique contenant tous les points d'accès du serveur, utilisez :
GET /api/openapi.json
GET /api/openapi.yaml
OBS ! Sachez que cette opération génère un document de plusieurs Mo.
Il est possible d'accéder à un document pour un point de terminaison spécifique en ajoutant soit openapi.json ou openapi.yaml au chemin racine d'un point de terminaison. Par exemple, pour générer un document pour les points de terminaison /users, utilisez :
GET /api/users/openapi.json
GET /api/users/openapi.yaml
Pour générer un document avec une sélection spécifique de chemins d'accès à la racine et/ou des étiquettes, le point d'accès général /openapi peut être utilisé avec un ou plusieurs sélecteurs étiquette et chemin.
GET /api/openapi/openapi.json?path=/users&path=/dataElements
GET /api/openapi/openapi.yaml?tag=system&tag=metadata
Les étiquettes disponibles sont :
utilisateurdonnéesmétadonnéesuianalysessystèmemessagerietrackerintégrationconnexionrequêtegestion
All endpoints that generate a OpenAPI document support the following optional request parameters:
failOnNameClash¶
When set to true, two or more types of same simple (unqualified) name are considered clashing and the generation fails with an error.
When set false (default), name clashes are resolved by adding numbers to the simple name to make each of them unique. As a result the names are not predictable or stable. Merging simple names with their intended markdown documentation based on name will be broken. This option is meant as a preview feature which should only be used during development.
failOnInconsistency¶
When set to true, a semantic inconsistency in the declaration causes the generation to fail with an error. Usually this indicates a programming mistake. For example, declaring a field both as required and having a default value.
When set to false, a semantic inconsistency is logged as warning but the generation proceeds. This might produce a document that contradicts itself semantically but is valid formally.