SPRING MVC – Documentation API
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 SpringDoc
– Configuration SpringDoc
– TP
© 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 [Link]
[Link] 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-ui dans le fichier [Link].
Et puis faire maven update de votre projet.
<dependency>
<groupId>[Link]</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
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
La page Swagger UI sera alors disponible à l’adresse:
[Link]
serveur : Le nom ou l’IP du serveur
port : Le port du serveur
context-path : Le chemin du contexte de l’application
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 8
Configuration SpringDoc
• Pour personnaliser l’interface utilisateur swagger-ui, Créez une
classe OpenAPIConfig dans un nouveau package appelé configuration.
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(infoAPI());
}
public Info infoAPI() {
return new Info().title(“SpringDoc-Demo")
.description("TP étude de cas")
.contact(contactAPI());
}
public Contact contactAPI() {
Contact contact = new Contact().name(“Equipe ASI
II")
.email(“*************@[Link]")
.url("[Link]
return contact;
}
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 9
Configuration SpringDoc
On peut aussi regrouper nos API en fonction des paquets, des chemins, etc. en
utilisant le GroupedOpenApi.
@Bean
public GroupedOpenApi productPublicApi() {
return [Link]()
.group("Only Product Management
API")
.pathsToMatch("/product/**")
.pathsToExclude("**")
.build();
}
Vous pouvez ensuite les sélectionner
dans swagger-ui en sélectionnant
la définition voulue.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 10
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 = “Product Management”)
@RestController
@RequestMapping(“product”)
public class ProductController {
@Autowired
IProductService productService;
@Operation(description = “Retrieve all
products”)
@PostMapping(“/getAll”)
public Produit addProduit() {
return [Link]();
}
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 11
TP
Exposer les services implémentés avec Swagger pour les
tester.
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 12
Si vous avez des questions, n’hésitez pas à nous
contacter :
Département Informatique
UP ASI
Bureau E204
© 2022-2023 – ESPRIT – Module Architecture des SI II (Spring) 13