springdoc openapi

IMPORTANT : springdoc-openapi v1.8.0 est la dernière version Open Source prenant en charge Spring Boot 2.x et 1.x.

Un support étendu pour le projet springdoc-openapi v1 est désormais disponible pour les organisations qui ont besoin d'un support au-delà de 2023.

Pour plus de détails, n'hésitez pas à nous contacter : [email protected]

springdoc-openapi est sur Open Collective. Si vous ❤️ ce projet pensez à devenir sponsor.

Ce projet est parrainé par

Table des matières

• Documentation complète
• Introduction
• Commencer
  • Bibliothèque pour l'intégration springdoc-openapi avec spring-boot et swagger-ui
  • Spring-boot avec les applications de démonstration OpenAPI.
    • Code source pour les applications de démonstration.
    • Démo Spring Boot 2 Web MVC avec OpenAPI 3.
    • Démo Spring Boot 2 WebFlux avec OpenAPI 3.
    • Démo Spring Boot 2 WebFlux avec points de terminaison fonctionnels OpenAPI 3.
    • Démo Spring Boot 2 et Spring Hateoas avec OpenAPI 3.
  • Intégration de la bibliothèque dans un projet Spring Boot 3.x sans le swagger-ui :
  • Gestion des erreurs pour REST à l'aide de @ControllerAdvice
  • Ajout d'informations sur l'API et de documentation sur la sécurité
  • prise en charge de spring-webflux avec les contrôleurs annotés
• Remerciements
  • Contributeurs
  • Assistance supplémentaire

Documentation complète

Introduction

La bibliothèque Java springdoc-openapi permet d'automatiser la génération de documentation API à l'aide de projets Spring Boot. springdoc-openapi fonctionne en examinant une application au moment de l'exécution pour déduire la sémantique de l'API basée sur les configurations Spring, la structure des classes et diverses annotations.

La bibliothèque génère automatiquement de la documentation dans des pages au format JSON/YAML et HTML. La documentation générée peut être complétée à l'aide d'annotations swagger-api .

Cette bibliothèque prend en charge :

• OuvrirAPI 3
• Spring-boot v3 (Java 17 et Jakarta EE 9)
• JSR-303, spécifiquement pour @NotNull, @Min, @Max et @Size.
• Swagger-interface utilisateur
• OAuth2
• Images natives GraalVM

La vidéo suivante présente la bibliothèque :

• https://youtu.be/utRxyPfFlDw

Pour la prise en charge de Spring-boot v3 , assurez-vous d'utiliser springdoc-openapi v2

Il s'agit d'un projet communautaire, non maintenu par les contributeurs Spring Framework (Pivotal)

Commencer

Bibliothèque pour l'intégration springdoc-openapi avec spring-boot et swagger-ui

• Déploie automatiquement swagger-ui sur une application Spring Boot 3.x
• La documentation sera disponible au format HTML, en utilisant les jars officiels swagger-ui.
• La page de l'interface utilisateur Swagger devrait alors être disponible sur http://server : port/context-path/swagger-ui.html et la description OpenAPI sera disponible à l'URL suivante pour le format json : http://server:port/context -chemin/v3/api-docs
  • server : Le nom du serveur ou l'IP
  • port : Le port du serveur
  • context-path : Le chemin contextuel de l'application
• La documentation peut également être disponible au format yaml, sur le chemin suivant : /v3/api-docs.yaml
• Ajoutez la bibliothèque springdoc-openapi-ui à la liste des dépendances de votre projet (aucune configuration supplémentaire n'est nécessaire) :

Maven

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Graduation

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Cette étape est facultative : pour le chemin personnalisé de la documentation swagger au format HTML, ajoutez une propriété springdoc personnalisée dans votre fichier de configuration spring-boot :

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

Spring-boot avec les applications de démonstration OpenAPI.

Code source pour les applications de démonstration.

Démo Spring Boot 3 Web MVC avec OpenAPI 3.

Démo Spring Boot 3 WebFlux avec OpenAPI 3.

Démo Spring Boot 3 WebFlux avec points de terminaison fonctionnels OpenAPI 3.

Démo Spring Boot 3 et Spring Cloud Function Web MVC.

Démo Spring Boot 3 et Spring Cloud Function WebFlux.

Démo Spring Boot 3 et Spring Cloud Gateway.

Intégration de la bibliothèque dans un projet Spring Boot 3.x sans le swagger-ui :

• La documentation sera disponible à l'url suivante pour le format json : http://server: port/context-path/v3/api-docs
  • server : Le nom du serveur ou l'IP
  • port : Le port du serveur
  • context-path : Le chemin contextuel de l'application
• La documentation sera également disponible au format yaml, sur le chemin suivant : /v3/api-docs.yaml
• Ajoutez la bibliothèque à la liste des dépendances de votre projet. (Aucune configuration supplémentaire n'est nécessaire)

Maven

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-api</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Graduation

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Cette étape est facultative : pour le chemin personnalisé de la documentation OpenAPI au format Json, ajoutez une propriété springdoc personnalisée dans votre fichier de configuration spring-boot :

 # /api-docs endpoint custom path
springdoc.api-docs.path =/api-docs

• Cette étape est facultative : si vous souhaitez désactiver les points de terminaison springdoc-openapi , ajoutez une propriété springdoc personnalisée dans votre fichier de configuration spring-boot :

 # disable api-docs
springdoc.api-docs.enabled =false

Gestion des erreurs pour REST à l'aide de @ControllerAdvice

Pour générer automatiquement la documentation, assurez-vous que toutes les méthodes déclarent les réponses du code HTTP à l'aide de l'annotation : @ResponseStatus.

Ajout d'informations sur l'API et de documentation sur la sécurité

La bibliothèque utilise des packages auto-configurés d'application Spring-boot pour rechercher les annotations suivantes dans les beans Spring : OpenAPIDefinition et Info. Ces annotations déclarent les informations API : titre, version, licence, sécurité, serveurs, balises, sécurité et externalDocs. Pour de meilleures performances de génération de documentation, déclarez les annotations @OpenAPIDefinition et @SecurityScheme dans un bean géré par Spring.

prise en charge de spring-webflux avec les contrôleurs annotés

• La documentation peut également être disponible au format yaml, sur le chemin suivant : /v3/api-docs.yaml
• Ajoutez la bibliothèque à la liste des dépendances de votre projet (Aucune configuration supplémentaire n'est nécessaire)

Maven

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webflux-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Graduation

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Cette étape est facultative : pour le chemin personnalisé de la documentation swagger au format HTML, ajoutez une propriété springdoc personnalisée dans votre fichier de configuration spring-boot :

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

Les bibliothèques springdoc-openapi sont hébergées sur le référentiel central maven. Les artefacts peuvent être consultés aux emplacements suivants :

Sorties :

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/ .

Instantanés :

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/ .

Remerciements

Contributeurs

springdoc-openapi est pertinent et mis à jour régulièrement grâce aux précieuses contributions de ses contributeurs.

Merci à tous pour votre soutien !

Assistance supplémentaire

• Spring Team - Merci pour leur soutien en partageant toutes les ressources pertinentes autour des projets Spring.
• JetBrains - Merci beaucoup d'avoir soutenu le projet springdoc-openapi.