SPRING WS – Spring Doc
Documentation API
OpenAPI Specification
UP ASI
Bureau E204
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 1
PLAN DU COURS
– Introduction
– OpenAPI Spécification
– Implémentations
– Intégration et Configuration de Spring Doc
– TP : Exposition de tous les Web Services : Chambre (déjà fait), Bloc,
Etudiant, Foyer, Reservation, Universite
– TP : Test de tous les Web Services avec Postman et avec Swagger (Spring
Doc
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 2
Introduction
Que signifie la documentation API ?
C’est un manuel de référence précis qui contient les informations nécessaires pour
travailler avec l’API, notamment des détails sur les fonctions, les classes, les types
de retour et les arguments.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 3
Introduction
Pourquoi ?
Les API ont pour vocation de servir à de nombreux développeurs.
Par conséquent, le développement d’une API nécessite une documentation
accessible et facilement utilisable.
Cette dernière doit toujours être à jour au fur et à mesure que le code et les
fonctionnalités de l’API évoluent.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 4
OpenAPI Specification
La documentation d'un service RESTful consiste essentiellement à décrire
les détails des requêtes HTTP qu'elle consomme et des réponses HTTP qu'elle
produit.
Préparer une documentation de qualité est une tâche difficile.
Il est donc important d'utiliser des outils appropriés à cette tâche.
Les formats de description d’API tels que la spécification OpenAPI(Swagger v3)
ont permis de simplifier la création et la maintenance de la documentation.
Elle garantit également que votre documentation soit à jour au fur et à mesure de
l'évolution de votre API.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 5
Implémentations
Pour l'intégration d'OAS dans notre application, nous devons faire appel à
l'implémentation qui nous convient.
Language Implémentation
Java springdoc-openapi
.Net Microsoft.OpenApi.net
Node.js oas3-remote-refs
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 6
Intégration SpringDoc
Pour commencer, nous allons simplement ajouter la dépendance springdoc-
openapi-starter-webmvc-ui dans le fichier pom.xml. Et puis faire maven update de
votre projet.
C'est tout, aucune configuration supplémentaire n'est nécessaire.
La documentation sera disponible au format HTML en utilisant l'outil swagger-ui.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 7
Intégration SpringDoc
Démarrer votre application Spring Boot :
Tomcat started on port(s): 8089 (http) with context path '/tpfoyer'
La page Swagger UI (Spring Doc) sera alors disponible à l’adresse:
http://server:port/context-path/swagger-ui/index.html
serveur : Le nom ou l’IP du serveur : localhost
port : Le port du serveur : 8089
context-path : Le chemin du contexte de l’application : tpfoyer :
http://localhost:8089/tpfoyer/swagger-ui/index.html
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 8
Intégration SpringDoc
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 9
Configuration SpringDoc
Nous pouvons aussi personnaliser la documentation grâce aux annotations:
• @Tag (@Api in swagger 2): permet d’ajouter une description pour chaque classe
RestController.
• @Operation(@ApiOperation in swagger 2): permet d’ajouter une description pour
chaque classe RestController.
@Tag(name = "Gestion Chambre")
@RestController
@AllArgsConstructor
@RequestMapping("/chambre")
public class ChambreRestController {
IChambreService chambreService;
// http://localhost:8089/tpfoyer/chambre/retrieve-all-chambres
@Operation(description = "récupérer toutes les chambres de la base de données")
@GetMapping("/retrieve-all-chambres")
public List<Chambre> getChambres() {
return chambreService.retrieveAllChambres();}
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 10
Configuration SpringDoc
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 11
Configuration SpringDoc
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 12
TP
Implémenter les Web Service CRUD pour toutes les
entités (Service + Controller) : Bloc, Foyer, Reservation,
Universite, Etudiant, (Chambre déjà implémentée la
semaine dernière normalement).
Utiliser Swagger (Spring Doc) et Postman pour tester les
services implémentés.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 13
