Projet MonDossierWeb
Pages enfant
  • MDWP -2- APIs Pégase

Comparaison des versions

Ancienne version 43

changes.mady.by.user Charlie Dubois

Sauvegardée le

comparé à

Nouvelle version Actuel

changes.mady.by.user Charlie Dubois

Sauvegardée le

Légende

  • Ces lignes ont été ajoutées. Ce mot a été ajouté.
  • Ces lignes ont été supprimées. Ce mot a été supprimé.
  • La mise en forme a été modifiée.

...

APIvariablesURL exemple
OAuth
url_authn_app_ticketshttps://authn-app.univ.pc-scol.fr/cas/v1/tickets
IDTurl_api_idthttps://idt.univ.pc-scol.fr/api/idt/v1
INS EXT
url_api_ins_ext
https://ins.univ.pc-scol.fr/api/v5/ins/ins/ext/v2
INSurl_api_inshttps://ins.univ.pc-scol.fr/api/ins/v1
PIECE EXTurl_api_piece_exthttps://piece.univ.pc-scol.fr/api/pie/ext/v1
CHC
url_api_chc
https://chc.univ.pc-scol.fr/api/chc/v6
COC
url_api_cochttps://coc.univ.pc-scol.fr/api/coc/publication/v1v2
PAI
url_api_pai
https://pai.univ.pc-scol.fr/api/v1

Méthodes utilisées

imprimerCertificatDeScolariteinsgestion/inscriptionscodeVoeucodePiececontenuINScontenuPiecelireCursusApprenant
URL (voir variables ci-dessus)Module/APIMéthodeUtilisation

url_authn_app_tickets?username=${username}&password=${password}&token=true

serveur OAuth
Récupération du Jeton JWT pour authentification des API
url_api_idt/etablissements/${etab}/identites/apprenants?codeApprenant=${codeApprenant}IDTrechercherIdentiteApprenantRechercher des identité d'apprenants
url_api_ins_ext/gestion/inscription/${etab}/${codeApprenant}INS EXT v2lireInscriptionsRécupération du dossier de l'apprenant et de ses inscriptions
url_api_ins/gestion/inscriptionsetablissement/${etab}/${codeApprenantuuidApprenant}/${codeVoeu}/certificat-de-scolariteINSgenererCertificatDeScolariteRécupération Génération du certificat de scolarité
url_api_piece_ext/etablissements/${etab}/codeApprenant/${codeApprenant}/codePeriode/${codePeriode}/codeChemin/${codeChemin}/photoPIECE EXTvisualiserPhotoRécupération de la photo de l'étudiant

url_api_chc/cursus-dca?codeApprenant={codeApprenant}

CHC

lireCusrsuApprenant

Récupération du cursus
url_api_coc/etablissements/${etab}/periodes/${codePeriode}/apprenants/${codeApprenant}/chemins/${chemin}COClisterCursusPubliableApprenantRécupération des notes et résultats de l'étudiant
url_api_coc/etablissements/${etab}/periodes/${codePeriode}/apprenants/${codeApprenant}/chemins/${chemin}/releves-de-notesCOClisterReleveDeNotePubliableApprenantLister les relevés de notes publiables
url_api_coc/modeles-releves-notes/${idReleve}/apprenants/${codeApprenant}/chemins/${chemin}/releves-de-notes-et-resultatsCOCgenererRelevesDeNotesEtResultatsPubliableApprenantGénérer un relevé de note
url_api_pai/pai/attestation-de-paiement/${etab}/${codeApprenant}/${codePeriode}PAIimprimerAttestationDePaiementRécupération de l'attestation de paiement


Tester une API

Nous allons voir comment tester le bon fonctionnement d'une API en la requêtant "à la main".

...

Bloc de code
POST https://authn-app.[univ].pc-scol.fr/cas/v1/tickets?username=[username]&password=[password]&token=true

Le username et le password à passer sont ceux permettant d'identifier MDW auprès du serveur OAuth de Pégase.

Ces informations correspondent aux paramètres suivant dans application.properties :

  • pegase.accesstoken.url
  • pegase.accesstoken.username
  • pegase.accesstoken.password

Appel de l'API

Bloc de code
GET https://ins.[univ].pc-scol.fr/api/v5/ins/gestion/inscription/[codeEtablissement]/[codeApprenant]/

...

Info
Via Postman le passage du token se fait facilement depuis l'onglet "Authorization" (Type "OAuth 2.0")

L'url de l'API et le code établissement correspondent aux paramètres suivant dans application.properties :

  • pegase.api.ins.url
  • pegase.etablissement


Génération des classes clientes java

...

Télécharger la version zip de node (https://nodejs.org/en/download/) et dézipper puis :

Bloc de code
languagebash
# Se rendre dans le répertoire d'installation
cd EC:/node-v14.16.0-win-x64

# Installer openapi-generator-cli
npm install @openapitools/openapi-generator-cli
npm install @openapitools/openapi-generator-cli -g

# Forcer l'utilisation de la version 5.4.0  
# /!\ IMPORTANT /!\  A vérifier avant chaque génération sous peine d'obtenir des imports non valides
openapi-generator-cli version-manager set 5.4.0

# Aide sur la config
npx @openapitools/openapi-generator-cli config-help -g jav

...

Exemple pour générer les classes de clients java des principales API :

Copier les YML descripteurs des APIs Pégase dans C:\tmp\YML et lancer depuis le répertoire où se trouve le YAML une génération des classes java :

Bloc de code
languagebash
titleGénération des clients java à partir des yaml
# Forcer l'utilisation de la version 5.4.0  
# /!\ IMPORTANT /!\  A vérifier avant chaque génération sous peine d'obtenir des imports non valides
openapi-generator-cli version-manager set 5.4.0

# INSIDT GESTION YAML 
npx @openapitools/openapi-generator-cli generate -i insidt-gestion-api-v5v1-201.0.0-rc.yaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.idt.invoker -p apiPackage=fr.univlorraine.pegase.idt.api.insgestion -p modelPackage=fr.univlorraine.pegase.idt.model.insgestion -p dateLibrary=java8java17-localdatetime

# CHCINS YAMLEXT 
npx @openapitools/openapi-generator-cli generate -i chcinscription-applicationext-api-v5v2-2.42.0-dev.20250424143719.ymlyaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.insext.invoker -p apiPackage=fr.univlorraine.pegase.insext.api.chc -p modelPackage=fr.univlorraine.pegase.insext.model -p dateLibrary=java17-localdatetime

# INS 
npx @openapitools/openapi-generator-cli generate -i ins-api-v1-1.0.0-rc.yaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.ins.invoker -p apiPackage=fr.univlorraine.pegase.ins.api -p modelPackage=fr.univlorraine.pegase.ins.model.chc -p dateLibrary=java8java17-localdatetime

# PIECE EXT 
npx @openapitools/openapi-generator-cli generate -i piece-ext-api-v1-1.2.0.yaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.pieceext.invoker --skip-validate-spec
 p apiPackage=fr.univlorraine.pegase.pieceext.api -p modelPackage=fr.univlorraine.pegase.pieceext.model -p dateLibrary=java17-localdatetime

# PAI YAML
npx @openapitools/openapi-generator-cli generate -i pai-api-v1-1627.0.0.yaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.pai.invoker -p apiPackage=fr.univlorraine.pegase.pai.api.pai -p modelPackage=fr.univlorraine.pegase.pai.model.pai -p dateLibrary=java8-localdatetime --skip-validate-spec
 
# COC GESTION YAML java17-localdatetime

# CHC
npx @openapitools/openapi-generator-cli generate -i chc-application-api-v6-6.8.0.yml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.chc.invoker -p apiPackage=fr.univlorraine.pegase.chc.api -p modelPackage=fr.univlorraine.pegase.chc.model -p dateLibrary=java17-localdatetime

# COC
npx @openapitools/openapi-generator-cli generate -i coc-publication-api-v1v2-2.1.4.0.yml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.coc.invoker -p apiPackage=fr.univlorraine.pegase.coc.api.coc -p modelPackage=fr.univlorraine.pegase.coc.model.coc -p dateLibrary=java8java17-localdatetime --skip-validate-spec

Récupérer le code généré dans le projet

Pour chaque API, récupérer Récupérer les classes des générées dans les répertoires :

  • / src/main/java/fr/univlorraine/pegase

    • /api

  • /{NOM_API}

    • /src/main/java/fr/univlorraine/pegase/model/{NOM_API}

Modification des classes générées

Dans les classes générées il faut remplacer l'annotation :

Bloc de code
@javax.annotation.Generated

par 

Bloc de code
@jakarta.annotation.Generated


Si des erreurs persistent à la compilation ou dans l'IDE, il peut être nécessaire d'apporter des modifications au code généré.

Exemple :

  • Corriger l'assignation aux énumérations dans les constructeurs des classes qui le nécessite. Par exemple, le code :

    Bloc de code
    this.canalCommunication = this.getClass().getSimpleName();
devient : 
this.canalCommunication = CanalCommunicationEnum.fromValue(this.getClass().getSimpleName());

    et certaines lignes 

    Bloc de code
    this.type = this.getClass().getSimpleName();
deviennent :
this.type = TypeEnum.fromValue(this.getClass().getSimpleName());


  • Supprimer l'attribut est1 et la constante SERIALIZED_NAME_EST1 de la classe fr.univlorraine.pegase.insext.model.Periode

Implémentation

Pour des exemples d'appels aux APIs effectués grâce aux classes générées ci-dessus, voir le code source du PegaseService sur github : https://github.com/EsupPortail/esup-mdw-pegase/blob/master/src/main/java/fr/univlorraine/mondossierweb/service/PegaseService.java

...