Architecture

MDW est autorisé à interroger les APIs Pégase en s'identifiant à l'aide d'un token (JWT). Ce dernier est obtenu en s'authentifiant (username + passwordd) auprès du serveur OAuth dédié.

Ce token a une durée de vie limitée. MDW garde donc ce token en mémoire et vérifie régulièrement sa validité afin de le renouveller si nécessaire.

APIs utilisées

Exemple de configuration

Voici un exemple des URLs à configurer dans la vue "Configuration" de l'application

Méthodes utilisées

Tester une API

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

Appeler une API s'effectue via une requête HTTP.

Pour être autorisé à appeler l'API d'un module Pégase, il faut préalablement avoir récupéré un token d'authentification.

Par exemple pour tester la méthode lireInscriptions de l'API INS (qui retourne la quasi totalité du dossier), il faut :

1. Faire un premier appel (POST) au serveur OAuth pour récupérer le token
2. Utiliser ce token pour appeler l'API (GET)

Récupération du token

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

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

Ajouter la chaîne "Bearer " (attention à bien ajouter l'espace) au début du token et le passer dans un header nommé "Authorization".

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

MDW embarque directement dans son code les classes java clientes utilisées pour interroger les APIs. Il n'y a pas de dépendance vers une librairie externe.

Pour générer ces classes java, OpenAPI Generator est utilisé depuis la v1.

Dans un soucis de transparence et afin de permettre de rejouer cette procédure (normalement pas nécessaire), voici, ci-dessous, la démarche utilisée lors du développement.

OpenAPI Generator Maven Plugin (version >= 2.3.10)

Depuis la version 2.3.10, le projet utilise le plugin Maven openapi-generator-maven-plugin pour générer les classes java permettant d'appeler les endpoints des APIs Pégase.

Pour chaque API ciblée il est nécessaire de copier dans le repertoire /src/main/resources/YML/ le contrat d'API yaml exporté du swagger exposé par Pégase.

Il faut ensuite indiquer le chemin vers ce yaml et les répertoires de destination dans la partie "configuration" du plugin maven. Exemple pour l'API IDT :  

<inputSpec>${project.basedir}/src/main/resources/YML/idt-ext-api-v1-1.5.0-rc.20260309165953.yaml</inputSpec>
<invokerPackage>fr.univlorraine.pegase.idt.invoker</invokerPackage>
<apiPackage>fr.univlorraine.pegase.idt.api</apiPackage>
<modelPackage>fr.univlorraine.pegase.idt.model</modelPackage>

Pour plus d'information sur le paramétrage du plugin vous pouvez vous référer au reste de la configuration visible dans le pom.xml

Pour générer les classes clientes il faut finalement exécuter la commande maven suivante : 

mvn openapi-generator:generate

Les classes sont générées dans le repertoire target/generated-sources/openapi/src

Il faut donc copier les packages et classes présents dans le répertoire target/generated-sources/openapi/src/fr/univlorraine/pegase/{nom_api} dans src/main/java/fr/univlorraine/pegase/{nom_api} 

  Attention : Il est indispensable de supprimer le repertoire target/generated-sources/openapi/src avant de relancer l'application. Sans cela des conflits empêcheront l'application de se lancer. 

OpenAPI Generator Standalone (version < 2.3.10)

Installation d'OpenAPI Generator

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

# Se rendre dans le répertoire d'installation
cd C:/node-v14.16.0-win-x64

# Installer 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

Génération du client java

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 :

# 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

# IDT   
npx @openapitools/openapi-generator-cli generate -i idt-api-v1-1.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 -p modelPackage=fr.univlorraine.pegase.idt.model -p dateLibrary=java17-localdatetime

# INS EXT 
npx @openapitools/openapi-generator-cli generate -i inscription-ext-api-v2-2.2.0-dev.20250424143719.yaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.insext.invoker -p apiPackage=fr.univlorraine.pegase.insext.api -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 -p dateLibrary=java17-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 -p apiPackage=fr.univlorraine.pegase.pieceext.api -p modelPackage=fr.univlorraine.pegase.pieceext.model -p dateLibrary=java17-localdatetime

# PAI
npx @openapitools/openapi-generator-cli generate -i pai-api-v1-27.0.0.yaml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.pai.invoker -p apiPackage=fr.univlorraine.pegase.pai.api -p modelPackage=fr.univlorraine.pegase.pai.model -p dateLibrary=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-v2-2.1.0.yml -g java -o C:/tmp/openapi-generator/ -p invokerPackage=fr.univlorraine.pegase.coc.invoker -p apiPackage=fr.univlorraine.pegase.coc.api -p modelPackage=fr.univlorraine.pegase.coc.model -p dateLibrary=java17-localdatetime

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

Récupérer les classes générées dans les répertoires :

Copier les classes générées dans le répertoire de destination du générateur et les copier dans le répertoire src correspondant du projet :

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

Modification des classes générées

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

@javax.annotation.Generated

par 

@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 :

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

  et certaines lignes 

  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