From 84d0b4fb9d43a4ea3eb703ae91bc98fa4a60c868 Mon Sep 17 00:00:00 2001
From: Emmanuel Viennet <emmanuel.viennet@gmail.com>
Date: Sun, 23 Jun 2024 17:40:48 +0200
Subject: [PATCH] Documentation API (QUERY pour carte syntaxique)

---
 app/api/etudiants.py     | 24 +++++++++++++++++-------
 app/api/formsemestres.py | 35 ++++++++++++++++++++++++++++++++++-
 app/api/partitions.py    |  8 +++++++-
 app/api/users.py         |  7 +++++++
 4 files changed, 65 insertions(+), 9 deletions(-)

diff --git a/app/api/etudiants.py b/app/api/etudiants.py
index 9b21db434..5ec9f04a5 100755
--- a/app/api/etudiants.py
+++ b/app/api/etudiants.py
@@ -89,12 +89,17 @@ def _get_etud_by_code(
 @scodoc
 @permission_required(Permission.ScoView)
 @as_json
-def etudiants_courants(long=False):
+def etudiants_courants(long: bool = False):
     """
-    La liste des étudiants des semestres "courants" (tous départements)
-    (date du jour comprise dans la période couverte par le sem.)
-    dans lesquels l'utilisateur a la permission ScoView
-    (donc tous si le dept du rôle est None).
+    La liste des étudiants des semestres "courants".
+    Considère tous les départements dans lesquels l'utilisateur a la
+    permission `ScoView` (donc tous si le dépt. du rôle est `None`),
+    et les formsemestres contenant la date courante,
+    ou à défaut celle indiquée en argument (au format ISO).
+
+    QUERY
+    -----
+    date_courante:<string:date_courante>
 
     Exemple de résultat :
         [
@@ -183,8 +188,13 @@ def etudiant(etudid: int = None, nip: str = None, ine: str = None):
 @permission_required(Permission.ScoView)
 def get_photo_image(etudid: int = None, nip: str = None, ine: str = None):
     """
-    Retourne la photo de l'étudiant
-    correspondant ou un placeholder si non existant.
+    Retourne la photo de l'étudiant ou un placeholder si non existant.
+    Le paramètre `size` peut prendre la valeur `small` (taille réduite, hauteur
+    environ 90 pixels) ou `orig` (défaut, image de la taille originale).
+
+    QUERY
+    -----
+    size:<string:size>
 
     etudid : l'etudid de l'étudiant
     nip : le code nip de l'étudiant
diff --git a/app/api/formsemestres.py b/app/api/formsemestres.py
index 664a663bf..7d91516dd 100644
--- a/app/api/formsemestres.py
+++ b/app/api/formsemestres.py
@@ -108,6 +108,17 @@ def formsemestres_query():
     dept_id : id du département
     ine ou nip: code d'un étudiant: ramène alors tous les semestres auxquels il est inscrit.
     etat: 0 si verrouillé, 1 sinon
+
+    QUERY
+    -----
+    etape_apo:<string:etape_apo>
+    annee_scolaire:<string:annee_scolaire>
+    dept_acronym:<string:dept_acronym>
+    dept_id:<int:dept_id>
+    etat:<int:etat>
+    nip:<string:nip>
+    ine:<string:ine>
+
     """
     etape_apo = request.args.get("etape_apo")
     annee_scolaire = request.args.get("annee_scolaire")
@@ -376,7 +387,16 @@ def formsemestre_programme(formsemestre_id: int):
 def formsemestre_etudiants(
     formsemestre_id: int, with_query: bool = False, long: bool = False
 ):
-    """Étudiants d'un formsemestre."""
+    """Étudiants d'un formsemestre.
+
+    Si l'état est spécifié, ne renvoie que les  inscrits (`I`), les
+    démissionnaires (`D`) ou les défaillants (`DEF`)
+
+    QUERY
+    -----
+    etat:<string:etat>
+
+    """
     query = FormSemestre.query.filter_by(id=formsemestre_id)
     if g.scodoc_dept:
         query = query.filter_by(dept_id=g.scodoc_dept_id)
@@ -531,6 +551,13 @@ def etat_evals(formsemestre_id: int):
 def formsemestre_resultat(formsemestre_id: int):
     """Tableau récapitulatif des résultats
     Pour chaque étudiant, son état, ses groupes, ses moyennes d'UE et de modules.
+
+    Si `format=raw`, ne converti pas les valeurs.
+
+    QUERY
+    -----
+    format:<string:format>
+
     """
     format_spec = request.args.get("format", None)
     if format_spec is not None and format_spec != "raw":
@@ -623,6 +650,12 @@ def formsemestre_edt(formsemestre_id: int):
 
     group_ids permet de filtrer sur les groupes ScoDoc.
     show_modules_titles affiche le titre complet du module (défaut), sinon juste le code.
+
+    QUERY
+    -----
+    group_ids:<string:group_ids>
+    show_modules_titles:<bool:show_modules_titles>
+
     """
     query = FormSemestre.query.filter_by(id=formsemestre_id)
     if g.scodoc_dept:
diff --git a/app/api/partitions.py b/app/api/partitions.py
index 7b47c3148..54c30355f 100644
--- a/app/api/partitions.py
+++ b/app/api/partitions.py
@@ -151,7 +151,13 @@ def etud_in_group(group_id: int):
 @permission_required(Permission.ScoView)
 @as_json
 def etud_in_group_query(group_id: int):
-    """Étudiants du groupe, filtrés par état"""
+    """Étudiants du groupe, filtrés par état (aucun, I, D, DEF)
+
+    QUERY
+    -----
+    etat:<string:etat>
+
+    """
     etat = request.args.get("etat")
     if etat not in {None, scu.INSCRIT, scu.DEMISSION, scu.DEF}:
         return json_error(API_CLIENT_ERROR, "etat: valeur invalide")
diff --git a/app/api/users.py b/app/api/users.py
index c038ffb8d..f1a600935 100644
--- a/app/api/users.py
+++ b/app/api/users.py
@@ -59,6 +59,13 @@ def users_info_query():
     Seuls les utilisateurs "accessibles" (selon les permissions) sont retournés.
     Si accès via API web,  le département de l'URL est ignoré, seules
     les permissions de l'utilisateur sont prises en compte.
+
+    QUERY
+    -----
+    active:<bool:active>
+    departement:<string:departement>
+    starts_with:<string:starts_with>
+
     """
     query = User.query
     active = request.args.get("active")