dubacq/ScoDoc
1
0
Fork 0
forked from ScoDoc/ScoDoc
Code Pull Requests Activity

Merge pull request 'Génération de la documentation API' (#969) from iziram/ScoDoc:master into master

Browse Source 
Reviewed-on: ScoDoc/ScoDoc#969
This commit is contained in:
Emmanuel Viennet 2024-07-25 08:44:38 +02:00
commit b3111769a1
4 changed files with 232 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
app/api/assiduites.py
View File

@ -58,9 +58,9 @@ def assiduite(assiduite_id: int = None):
"date_fin": "2022-10-31T10:00+01:00", "date_fin": "2022-10-31T10:00+01:00",
"etat": "retard", "etat": "retard",
"desc": "une description", "desc": "une description",
"user_id: 1 or null, "user_id": 1 or null,
"user_name" : login scodoc or null "user_name" : login scodoc or null,
"user_nom_complet": "Marie Dupont" "user_nom_complet": "Marie Dupont",
"est_just": False or True, "est_just": False or True,
} }
``` ```
@ -132,42 +132,6 @@ def assiduites_count(
""" """
Retourne le nombre d'assiduités d'un étudiant. Retourne le nombre d'assiduités d'un étudiant.
Un filtrage peut être donné avec une `query`.
Les différents filtres :
- Type (type de comptage -> journee, demi, heure, nombre d'assiduite):
query?type=(journee, demi, heure) -> une seule valeur parmis les trois
ex: .../query?type=heure
Comportement par défaut : compte le nombre d'assiduité enregistrée
- Etat (etat de l'étudiant -> absent, present ou retard):
`query?etat=[- liste des états séparé par une virgule -]`
ex: .../query?etat=present,retard
- Date debut
(date de début de l'assiduité, sont affichés les assiduités
dont la date de début est supérieur ou égale à la valeur donnée):
query?date_debut=[- date au format iso -]
ex: query?date_debut=2022-11-03T08:00+01:00
Date fin
(date de fin de l'assiduité, sont affichés les assiduités
dont la date de fin est inférieure ou égale à la valeur donnée):
query?date_fin=[- date au format iso -]
ex: query?date_fin=2022-11-03T10:00+01:00
Moduleimpl_id (l'id du module concerné par l'assiduité):
query?moduleimpl_id=[- int ou vide -]
ex: query?moduleimpl_id=1234
query?moduleimpl_od=
Formsemstre_id (l'id du formsemestre concerné par l'assiduité)
query?formsemestre_id=[int]
ex query?formsemestre_id=3
user_id (l'id de l'auteur de l'assiduité)
query?user_id=[int]
ex query?user_id=3
est_just (si l'assiduité est justifié (fait aussi filtre par abs/retard))
query?est_just=[bool]
query?est_just=f
query?est_just=t
QUERY QUERY
----- -----
user_id:<int:user_id> user_id:<int:user_id>
@ -180,6 +144,18 @@ def assiduites_count(
metric:<array[string]:metric> metric:<array[string]:metric>
split:<bool:split> split:<bool:split>
PARAMS
-----
user_id:l'id de l'auteur de l'assiduité
est_just:si l'assiduité est justifiée (fait aussi filtre abs/retard)
moduleimpl_id:l'id du module concerné par l'assiduité
date_debut:date de début de l'assiduité (supérieur ou égal)
date_fin:date de fin de l'assiduité (inférieur ou égal)
etat:etat de l'étudiant &rightarrow; absent, present ou retard
formsemestre_id:l'identifiant du formsemestre concerné par l'assiduité
metric: la/les métriques de comptage (journee, demi, heure, compte)
split: divise le comptage par état
""" """
# Récupération de l'étudiant # Récupération de l'étudiant
@ -235,39 +211,6 @@ def assiduites_count(
def assiduites(etudid: int = None, nip=None, ine=None, with_query: bool = False): def assiduites(etudid: int = None, nip=None, ine=None, with_query: bool = False):
""" """
Retourne toutes les assiduités d'un étudiant Retourne toutes les assiduités d'un étudiant
chemin : /assiduites/<int:etudid>
Un filtrage peut être donné avec une query
chemin : /assiduites/<int:etudid>/query?
Les différents filtres :
Etat (etat de l'étudiant -> absent, present ou retard):
query?etat=[- liste des états séparé par une virgule -]
ex: .../query?etat=present,retard
Date debut
(date de début de l'assiduité, sont affichés les assiduités
dont la date de début est supérieur ou égale à la valeur donnée):
query?date_debut=[- date au format iso -]
ex: query?date_debut=2022-11-03T08:00+01:00
Date fin
(date de fin de l'assiduité, sont affichés les assiduités
dont la date de fin est inférieure ou égale à la valeur donnée):
query?date_fin=[- date au format iso -]
ex: query?date_fin=2022-11-03T10:00+01:00
Moduleimpl_id (l'id du module concerné par l'assiduité):
query?moduleimpl_id=[- int ou vide -]
ex: query?moduleimpl_id=1234
query?moduleimpl_od=
Formsemstre_id (l'id du formsemestre concerné par l'assiduité)
query?formsemstre_id=[int]
ex query?formsemestre_id=3
user_id (l'id de l'auteur de l'assiduité)
query?user_id=[int]
ex query?user_id=3
est_just (si l'assiduité est justifié (fait aussi filtre par abs/retard))
query?est_just=[bool]
query?est_just=f
query?est_just=t
QUERY QUERY
----- -----
@ -279,6 +222,16 @@ def assiduites(etudid: int = None, nip=None, ine=None, with_query: bool = False)
etat:<array[string]:etat> etat:<array[string]:etat>
formsemestre_id:<int:formsemestre_id> formsemestre_id:<int:formsemestre_id>
PARAMS
-----
user_id:l'id de l'auteur de l'assiduité
est_just:si l'assiduité est justifiée (fait aussi filtre abs/retard)
moduleimpl_id:l'id du module concerné par l'assiduité
date_debut:date de début de l'assiduité (supérieur ou égal)
date_fin:date de fin de l'assiduité (inférieur ou égal)
etat:etat de l'étudiant &rightarrow; absent, present ou retard
formsemestre_id:l'identifiant du formsemestre concerné par l'assiduité
""" """
# Récupération de l'étudiant # Récupération de l'étudiant
@ -333,7 +286,9 @@ def assiduites_evaluations(etudid: int = None, nip=None, ine=None):
Pour chaque évaluation, retourne la liste des objets assiduités Pour chaque évaluation, retourne la liste des objets assiduités
sur la plage de l'évaluation sur la plage de l'évaluation
Présentation du retour : Exemple de résultat:
```json
[ [
{ {
"evaluation_id": 1234, "evaluation_id": 1234,
@ -345,6 +300,7 @@ def assiduites_evaluations(etudid: int = None, nip=None, ine=None):
] ]
} }
] ]
```
""" """
# Récupération de l'étudiant # Récupération de l'étudiant
@ -372,7 +328,10 @@ def assiduites_evaluations(etudid: int = None, nip=None, ine=None):
def evaluation_assiduites(evaluation_id): def evaluation_assiduites(evaluation_id):
""" """
Retourne les objets assiduités de chaque étudiant sur la plage de l'évaluation Retourne les objets assiduités de chaque étudiant sur la plage de l'évaluation
Présentation du retour :
Exemple de résultat:
```json
{ {
"<etudid>" : [ "<etudid>" : [
{ {
@ -381,6 +340,11 @@ def evaluation_assiduites(evaluation_id):
}, },
] ]
} }
```
CATEGORY
--------
evaluations
""" """
# Récupération de l'évaluation # Récupération de l'évaluation
try: try:
@ -409,37 +373,6 @@ def assiduites_group(with_query: bool = False):
Retourne toutes les assiduités d'un groupe d'étudiants Retourne toutes les assiduités d'un groupe d'étudiants
chemin : /assiduites/group/query?etudids=1,2,3 chemin : /assiduites/group/query?etudids=1,2,3
Un filtrage peut être donné avec une query
chemin : /assiduites/group/query?etudids=1,2,3
Les différents filtres :
Etat (etat de l'étudiant -> absent, present ou retard):
query?etat=[- liste des états séparé par une virgule -]
ex: .../query?etat=present,retard
Date debut
(date de début de l'assiduité, sont affichés les assiduités
dont la date de début est supérieur ou égale à la valeur donnée):
query?date_debut=[- date au format iso -]
ex: query?date_debut=2022-11-03T08:00+01:00
Date fin
(date de fin de l'assiduité, sont affichés les assiduités
dont la date de fin est inférieure ou égale à la valeur donnée):
query?date_fin=[- date au format iso -]
ex: query?date_fin=2022-11-03T10:00+01:00
Moduleimpl_id (l'id du module concerné par l'assiduité):
query?moduleimpl_id=[- int ou vide -]
ex: query?moduleimpl_id=1234
query?moduleimpl_od=
Formsemstre_id (l'id du formsemestre concerné par l'assiduité)
query?formsemstre_id=[int]
ex query?formsemestre_id=3
user_id (l'id de l'auteur de l'assiduité)
query?user_id=[int]
ex query?user_id=3
est_just (si l'assiduité est justifié (fait aussi filtre par abs/retard))
query?est_just=[bool]
query?est_just=f
query?est_just=t
QUERY QUERY
----- -----
@ -449,9 +382,20 @@ def assiduites_group(with_query: bool = False):
date_debut:<string:date_debut_iso> date_debut:<string:date_debut_iso>
date_fin:<string:date_fin_iso> date_fin:<string:date_fin_iso>
etat:<array[string]:etat> etat:<array[string]:etat>
etudids:<array[int]:etudids etudids:<array[int]:etudids>
formsemestre_id:<int:formsemestre_id> formsemestre_id:<int:formsemestre_id>
PARAMS
-----
user_id:l'id de l'auteur de l'assiduité
est_just:si l'assiduité est justifiée (fait aussi filtre abs/retard)
moduleimpl_id:l'id du module concerné par l'assiduité
date_debut:date de début de l'assiduité (supérieur ou égal)
date_fin:date de fin de l'assiduité (inférieur ou égal)
etat:etat de l'étudiant &rightarrow; absent, present ou retard
etudids:liste des ids des étudiants concernés par la recherche
formsemestre_id:l'identifiant du formsemestre concerné par l'assiduité
""" """
# Récupération des étudiants dans la requête # Récupération des étudiants dans la requête
@ -511,6 +455,7 @@ def assiduites_group(with_query: bool = False):
@permission_required(Permission.ScoView) @permission_required(Permission.ScoView)
def assiduites_formsemestre(formsemestre_id: int, with_query: bool = False): def assiduites_formsemestre(formsemestre_id: int, with_query: bool = False):
"""Retourne toutes les assiduités du formsemestre """Retourne toutes les assiduités du formsemestre
QUERY QUERY
----- -----
user_id:<int:user_id> user_id:<int:user_id>
@ -519,6 +464,16 @@ def assiduites_formsemestre(formsemestre_id: int, with_query: bool = False):
date_debut:<string:date_debut_iso> date_debut:<string:date_debut_iso>
date_fin:<string:date_fin_iso> date_fin:<string:date_fin_iso>
etat:<array[string]:etat> etat:<array[string]:etat>
PARAMS
-----
user_id:l'id de l'auteur de l'assiduité
est_just:si l'assiduité est justifiée (fait aussi filtre abs/retard)
moduleimpl_id:l'id du module concerné par l'assiduité
date_debut:date de début de l'assiduité (supérieur ou égal)
date_fin:date de fin de l'assiduité (inférieur ou égal)
etat:etat de l'étudiant &rightarrow; absent, present ou retard
formsemestre_id:l'identifiant du formsemestre concerné par l'assiduité
""" """
# Récupération du formsemestre à partir du formsemestre_id # Récupération du formsemestre à partir du formsemestre_id
@ -582,6 +537,18 @@ def assiduites_formsemestre_count(
formsemestre_id:<int:formsemestre_id> formsemestre_id:<int:formsemestre_id>
metric:<array[string]:metric> metric:<array[string]:metric>
split:<bool:split> split:<bool:split>
PARAMS
-----
user_id:l'id de l'auteur de l'assiduité
est_just:si l'assiduité est justifiée (fait aussi filtre abs/retard)
moduleimpl_id:l'id du module concerné par l'assiduité
date_debut:date de début de l'assiduité (supérieur ou égal)
date_fin:date de fin de l'assiduité (inférieur ou égal)
etat:etat de l'étudiant &rightarrow; absent, present ou retard
formsemestre_id:l'identifiant du formsemestre concerné par l'assiduité
metric: la/les métriques de comptage (journee, demi, heure, compte)
split: divise le comptage par état
""" """
# Récupération du formsemestre à partir du formsemestre_id # Récupération du formsemestre à partir du formsemestre_id
@ -633,7 +600,10 @@ def assiduites_formsemestre_count(
def assiduite_create(etudid: int = None, nip=None, ine=None): def assiduite_create(etudid: int = None, nip=None, ine=None):
""" """
Enregistrement d'assiduités pour un étudiant (etudid) Enregistrement d'assiduités pour un étudiant (etudid)
La requête doit avoir un content type "application/json":
DATA
----
```json
[ [
{ {
"date_debut": str, "date_debut": str,
@ -649,6 +619,7 @@ def assiduite_create(etudid: int = None, nip=None, ine=None):
} }
... ...
] ]
```
""" """
# Récupération de l'étudiant # Récupération de l'étudiant
@ -702,7 +673,10 @@ def assiduite_create(etudid: int = None, nip=None, ine=None):
def assiduites_create(): def assiduites_create():
""" """
Création d'une assiduité ou plusieurs assiduites Création d'une assiduité ou plusieurs assiduites
La requête doit avoir un content type "application/json":
DATA
----
```json
[ [
{ {
"date_debut": str, "date_debut": str,
@ -715,12 +689,12 @@ def assiduites_create():
"date_fin": str, "date_fin": str,
"etat": str, "etat": str,
"etudid":int, "etudid":int,
"moduleimpl_id": int, "moduleimpl_id": int,
"desc":str, "desc":str,
} }
... ...
] ]
```
""" """
@ -891,13 +865,14 @@ def assiduite_delete():
""" """
Suppression d'une assiduité à partir de son id Suppression d'une assiduité à partir de son id
Forme des données envoyées : DATA
----
```json
[ [
<assiduite_id:int>, <assiduite_id:int>,
... ...
] ]
```
""" """
# Récupération des ids envoyés dans la liste # Récupération des ids envoyés dans la liste
@ -972,13 +947,17 @@ def _delete_one(assiduite_id: int) -> tuple[int, str]:
def assiduite_edit(assiduite_id: int): def assiduite_edit(assiduite_id: int):
""" """
Edition d'une assiduité à partir de son id Edition d'une assiduité à partir de son id
La requête doit avoir un content type "application/json":
DATA
----
```json
{ {
"etat"?: str, "etat"?: str,
"moduleimpl_id"?: int "moduleimpl_id"?: int
"desc"?: str "desc"?: str
"est_just"?: bool "est_just"?: bool
} }
```
""" """
# Récupération de l'assiduité à modifier # Récupération de l'assiduité à modifier
@ -1020,7 +999,10 @@ def assiduite_edit(assiduite_id: int):
def assiduites_edit(): def assiduites_edit():
""" """
Edition de plusieurs assiduités Edition de plusieurs assiduités
La requête doit avoir un content type "application/json":
DATA
----
```json
[ [
{ {
"assiduite_id" : int, "assiduite_id" : int,
@ -1030,6 +1012,7 @@ def assiduites_edit():
"est_just"?: bool "est_just"?: bool
} }
] ]
```
""" """
edit_list: list[object] = request.get_json(force=True) edit_list: list[object] = request.get_json(force=True)

85
app/api/justificatifs.py
View File

@ -92,38 +92,26 @@ def justificatif(justif_id: int = None):
def justificatifs(etudid: int = None, nip=None, ine=None, with_query: bool = False): def justificatifs(etudid: int = None, nip=None, ine=None, with_query: bool = False):
""" """
Retourne toutes les assiduités d'un étudiant Retourne toutes les assiduités d'un étudiant
chemin : /justificatifs/<int:etudid>
Un filtrage peut être donné avec une query
chemin : /justificatifs/<int:etudid>/query?
Les différents filtres :
Etat (etat du justificatif -> validé, non validé, modifé, en attente):
query?etat=[- liste des états séparé par une virgule -]
ex: .../query?etat=validé,modifié
Date debut
(date de début du justificatif, sont affichés les justificatifs
dont la date de début est supérieur ou égale à la valeur donnée):
query?date_debut=[- date au format iso -]
ex: query?date_debut=2022-11-03T08:00+01:00
Date fin
(date de fin du justificatif, sont affichés les justificatifs
dont la date de fin est inférieure ou égale à la valeur donnée):
query?date_fin=[- date au format iso -]
ex: query?date_fin=2022-11-03T10:00+01:00
user_id (l'id de l'auteur du justificatif)
query?user_id=[int]
ex query?user_id=3
QUERY QUERY
----- -----
user_id:<int:user_id> user_id:<int:user_id>
est_just:<bool:est_just>
date_debut:<string:date_debut_iso> date_debut:<string:date_debut_iso>
date_fin:<string:date_fin_iso> date_fin:<string:date_fin_iso>
etat:<array[string]:etat> etat:<array[string]:etat>
order:<bool:order> order:<bool:order>
courant:<bool:courant> courant:<bool:courant>
group_id:<int:group_id> group_id:<int:group_id>
PARAMS
-----
user_id:l'id de l'auteur du justificatif
date_debut:date de début du justificatif (supérieur ou égal)
date_fin:date de fin du justificatif (inférieur ou égal)
etat:etat du justificatif &rightarrow; valide, non_valide, attente, modifie
order:retourne les justificatifs dans l'ordre décroissant (non vide = True)
courant:retourne les justificatifs de l'année courante (bool : v/t ou f)
group_id:<int:group_id>
""" """
# Récupération de l'étudiant # Récupération de l'étudiant
etud: Identite = tools.get_etud(etudid, nip, ine) etud: Identite = tools.get_etud(etudid, nip, ine)
@ -176,6 +164,16 @@ def justificatifs_dept(dept_id: int = None, with_query: bool = False):
order:<bool:order> order:<bool:order>
courant:<bool:courant> courant:<bool:courant>
group_id:<int:group_id> group_id:<int:group_id>
PARAMS
-----
user_id:l'id de l'auteur du justificatif
date_debut:date de début du justificatif (supérieur ou égal)
date_fin:date de fin du justificatif (inférieur ou égal)
etat:etat du justificatif &rightarrow; valide, non_valide, attente, modifie
order:retourne les justificatifs dans l'ordre décroissant (non vide = True)
courant:retourne les justificatifs de l'année courante (bool : v/t ou f)
group_id:<int:group_id>
""" """
# Récupération du département et des étudiants du département # Récupération du département et des étudiants du département
@ -259,6 +257,16 @@ def justificatifs_formsemestre(formsemestre_id: int, with_query: bool = False):
order:<bool:order> order:<bool:order>
courant:<bool:courant> courant:<bool:courant>
group_id:<int:group_id> group_id:<int:group_id>
PARAMS
-----
user_id:l'id de l'auteur du justificatif
date_debut:date de début du justificatif (supérieur ou égal)
date_fin:date de fin du justificatif (inférieur ou égal)
etat:etat du justificatif &rightarrow; valide, non_valide, attente, modifie
order:retourne les justificatifs dans l'ordre décroissant (non vide = True)
courant:retourne les justificatifs de l'année courante (bool : v/t ou f)
group_id:<int:group_id>
""" """
# Récupération du formsemestre # Récupération du formsemestre
@ -307,7 +315,10 @@ def justificatifs_formsemestre(formsemestre_id: int, with_query: bool = False):
def justif_create(etudid: int = None, nip=None, ine=None): def justif_create(etudid: int = None, nip=None, ine=None):
""" """
Création d'un justificatif pour l'étudiant (etudid) Création d'un justificatif pour l'étudiant (etudid)
La requête doit avoir un content type "application/json":
DATA
----
```json
[ [
{ {
"date_debut": str, "date_debut": str,
@ -322,6 +333,7 @@ def justif_create(etudid: int = None, nip=None, ine=None):
} }
... ...
] ]
```
""" """
@ -452,14 +464,17 @@ def _create_one(
def justif_edit(justif_id: int): def justif_edit(justif_id: int):
""" """
Edition d'un justificatif à partir de son id Edition d'un justificatif à partir de son id
La requête doit avoir un content type "application/json":
DATA
----
```json
{ {
"etat"?: str, "etat"?: str,
"raison"?: str "raison"?: str
"date_debut"?: str "date_debut"?: str
"date_fin"?: str "date_fin"?: str
} }
```
""" """
# Récupération du justificatif à modifier # Récupération du justificatif à modifier
@ -566,14 +581,14 @@ def justif_delete():
""" """
Suppression d'un justificatif à partir de son id Suppression d'un justificatif à partir de son id
Forme des données envoyées : DATA
----
```json
[ [
<justif_id:int>, <justif_id:int>,
... ...
] ]
```
""" """
# Récupération des justif_ids # Récupération des justif_ids
@ -648,6 +663,8 @@ def _delete_one(justif_id: int) -> tuple[int, str]:
def justif_import(justif_id: int = None): def justif_import(justif_id: int = None):
""" """
Importation d'un fichier (création d'archive) Importation d'un fichier (création d'archive)
> Procédure d'importation de fichier : [importer un justificatif](FichiersJustificatifs.md#importer-un-fichier)
""" """
# On vérifie qu'un fichier a bien été envoyé # On vérifie qu'un fichier a bien été envoyé
@ -699,6 +716,8 @@ def justif_export(justif_id: int | None = None, filename: str | None = None):
""" """
Retourne un fichier d'une archive d'un justificatif. Retourne un fichier d'une archive d'un justificatif.
La permission est ScoView + (AbsJustifView ou être l'auteur du justifcatif) La permission est ScoView + (AbsJustifView ou être l'auteur du justifcatif)
> Procédure de téléchargement de fichier : [télécharger un justificatif](FichiersJustificatifs.md#télécharger-un-fichier)
""" """
# On récupère le justificatif concerné # On récupère le justificatif concerné
justificatif_unique = Justificatif.get_justificatif(justif_id) justificatif_unique = Justificatif.get_justificatif(justif_id)
@ -736,14 +755,20 @@ def justif_export(justif_id: int | None = None, filename: str | None = None):
def justif_remove(justif_id: int = None): def justif_remove(justif_id: int = None):
""" """
Supression d'un fichier ou d'une archive Supression d'un fichier ou d'une archive
{
"remove": <"all"/"list">
> Procédure de suppression de fichier : [supprimer un justificatif](FichiersJustificatifs.md#supprimer-un-fichier)
DATA
----
```json
{
"remove": <"all"/"list">,
"filenames"?: [ "filenames"?: [
<filename:str>, <filename:str>,
... ...
] ]
} }
```
""" """
# On récupère le dictionnaire # On récupère le dictionnaire

31
app/templates/apidoc.j2 Normal file
View File

@ -0,0 +1,31 @@
#### **`{{doc.nom}}`**
{% if doc.routes %}
{% if doc.routes|length == 1 %}
* **Route:** `{{doc.routes[0]|safe}}`
{% else %}
* **Routes:**
{% for route in doc.routes %}
* `{{route|safe}}`
{% endfor %}
{% endif %}
{% endif %}
* **Méthode:** `{{doc.method}}`
* **Permission:** `{{doc.permission}}`
{% if doc.params %}
* **Paramètres:**
{% for param in doc.params %}
* `{{param.nom|safe}}` : {{param.description|safe}}
{% endfor %}
{% endif %}
{% if doc.description %}
* **Description:** {{doc.description|safe}}
{% endif %}
{% if doc.data %}
* **Data:** {{doc.data|safe}}
{% endif %}
{% if doc.sample %}
* **Exemple de résultat:** [{{doc.sample.nom}}](./samples/sample_{{doc.sample.href}})
{% else %}
{% endif %}

116
tools/create_api_map.py
View File

@ -4,10 +4,12 @@ Script permettant de générer une carte SVG de l'API de ScoDoc
Écrit par Matthias HARTMANN Écrit par Matthias HARTMANN
""" """
import sys
import xml.etree.ElementTree as ET import xml.etree.ElementTree as ET
import re import re
from app.auth.models import Permission from app.auth.models import Permission
from flask import render_template
class COLORS: class COLORS:
@ -507,6 +509,14 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
if child.query and not href.endswith("-query"): if child.query and not href.endswith("-query"):
href += "-query" href += "-query"
# category
category: str = func.__module__.replace("app.api.", "")
mod_doc: str = sys.modules[func.__module__].__doc__ or ""
mod_doc_dict: dict = _parse_doc_string(mod_doc)
if mod_doc_dict.get("CATEGORY"):
category = mod_doc_dict["CATEGORY"][0].strip()
permissions: str permissions: str
try: try:
permissions: str = ", ".join( permissions: str = ", ".join(
@ -524,6 +534,7 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
"permission": permissions, "permission": permissions,
"description": doc_dict.get("", ""), "description": doc_dict.get("", ""),
"params": doc_dict.get("PARAMS", ""), "params": doc_dict.get("PARAMS", ""),
"category": doc_dict.get("CATEGORY", [False])[0] or category,
} }
# On met à jour le token courant pour le prochain segment # On met à jour le token courant pour le prochain segment
@ -543,8 +554,6 @@ def gen_api_map(app, endpoint_start="api."):
puis génère un fichier SVG à partir de cet arbre puis génère un fichier SVG à partir de cet arbre
""" """
print("DEBUG", app.view_functions["apiweb.user_info"].scodoc_permission)
api_map, doctable_lines = analyze_api_routes(app, endpoint_start) api_map, doctable_lines = analyze_api_routes(app, endpoint_start)
# On génère le SVG à partir de l'arbre de Token # On génère le SVG à partir de l'arbre de Token
@ -870,88 +879,61 @@ def _write_gen_table(table: str, filename: str = "/tmp/api_table.md"):
) )
if __name__ == "__main__":
# Exemple d'utilisation de la classe Token
# Exemple simple de création d'un arbre de Token
# root = Token("api")
# child1 = Token("assiduites", leaf=True)
# child1.func_name = "assiduites_get"
# child2 = Token("count")
# child22 = Token("all")
# child23 = Token(
# "query",
# query={
# "etat": "<string:etat>",
# "moduleimpl_id": "<int:moduleimpl_id>",
# "count": "<int:count>",
# "formsemestre_id": "<int:formsemestre_id>",
# },
# )
# child3 = Token("justificatifs", "POST")
# child3.func_name = "justificatifs_post"
# root.add_child(child1)
# child1.add_child(child2)
# child2.add_child(child22)
# child2.add_child(child23)
# root.add_child(child3)
# group_element = root.to_svg_group()
# generate_svg(group_element, "/tmp/api_map.svg")
dt: dict = parse_doctable_doc(parse_doctable_doc.__doc__)
md: str = "POST"
hf: str = "assiduites-query"
doc: dict = {
"doctable": dt,
"method": md,
"href": hf,
}
print(_gen_table([doc]))
def doc_route(doctable: dict) -> str: def doc_route(doctable: dict) -> str:
"""Generate markdown doc for a route""" """Generate markdown doc for a route"""
doc = f""" jinja_obj: dict = {}
#### **`{doctable['nom']}`** jinja_obj.update(doctable)
jinja_obj["nom"] = doctable["nom"].strip() # on retire les caractères blancs
"""
if doctable.get("routes"):
if len(doctable["routes"]) == 1:
doc += f"""* ** Route :** `{doctable["routes"][0]}`\n"""
else:
doc += "* ** Routes :**\n"
for route in doctable["routes"]:
doc += f""" * `{route}`\n"""
doc += f"""* **Méthode: {doctable['method']}**
* **Permission: `{doctable.get('permission', '')}`**
"""
if doctable.get("params"): if doctable.get("params"):
jinja_obj["params"] = []
for param in doctable["params"]: for param in doctable["params"]:
frags = param.split(":", maxsplit=1) frags = param.split(":", maxsplit=1)
if len(frags) == 2: if len(frags) == 2:
name, descr = frags name, descr = frags
jinja_obj["params"].append(
{"nom": name.strip(), "description": descr.strip()}
)
else: else:
print(f"Warning: {doctable['nom']} : invalid PARAMS {param}") print(f"Warning: {doctable['nom']} : invalid PARAMS {param}")
name, descr = param, ""
doc += f""" * `{name}`: {descr}\n"""
if doctable.get("data"):
doc += f"""* **Data:** {doctable['data']}\n"""
if doctable.get("description"): if doctable.get("description"):
descr = "\n".join(s for s in doctable["description"]) descr = "\n".join(s for s in doctable["description"])
doc += f"""* **Description:** {descr}\n""" jinja_obj["description"] = descr.strip()
return doc
jinja_obj["sample"] = {
"nom": f"{jinja_obj['nom']}.json",
"href": f"{jinja_obj['nom'].replace('_', '-')}.json.md",
}
return render_template("apidoc.j2", doc=jinja_obj)
def gen_api_doc(app, endpoint_start="api."): def gen_api_doc(app, endpoint_start="api."):
"commande gen-api-doc" "commande gen-api-doc"
_, doctable_lines = analyze_api_routes(app, endpoint_start) _, doctable_lines = analyze_api_routes(app, endpoint_start)
mddoc = "\n".join(
doc_route(doctable) mddoc: str = ""
for doctable in sorted(doctable_lines.values(), key=lambda x: x["nom"])
) categories: dict = {}
for value in doctable_lines.values():
category = value["category"]
if category not in categories:
categories[category] = []
categories[category].append(value)
# sort categories by name
categories: dict = dict(sorted(categories.items(), key=lambda x: x[0]))
category: str
routes: list[dict]
for category, routes in categories.items():
# sort routes by name
routes.sort(key=lambda x: x["nom"])
mddoc += f"### API {category.capitalize()}\n\n"
for route in routes:
mddoc += doc_route(route)
mddoc += "\n\n"
fname = "/tmp/apidoc.md" fname = "/tmp/apidoc.md"
with open(fname, "w", encoding="utf-8") as f: with open(fname, "w", encoding="utf-8") as f: