Présentation Swagger
1. Qu'est-ce que Swagger
En tant que développement de programme back-end, nous avons écrit plusieurs projets d'interface back-end plus ou moins, qu'il s'agisse d'écrire une interface de téléphone mobile ou le projet actuel de séparation front-end à chaud, le front-end et le back-end sont développés par différents ingénieurs, puis ce La communication entre eux est connectée via des documents d'interface. Mais il y a souvent de nombreux problèmes. Les programmeurs back-end pensent qu'il faut trop de temps et d'énergie pour écrire les documents d'interface et la maintenance, et le front-end pense que les changements et les mises à jour des documents d'interface ne sont pas opportuns, ce qui conduit à des problèmes d'appels entre programmes. Peut-il simplifier la rédaction des documents d'interface et les générer directement automatiquement? Bien sûr! C'est ainsi qu'est né Swagger, un outil de génération automatique en ligne de documents d'interface.
Swagger est un framework standardisé et complet pour générer, décrire, appeler et visualiser des services Web de style RESTful. L'objectif général est de mettre à jour le client et le système de fichiers à la même vitesse que le serveur. Les méthodes de fichiers, les paramètres et les modèles sont étroitement intégrés dans le code côté serveur, ce qui permet à l'API de toujours rester synchronisée. Swagger n'a jamais été aussi simple à déployer, gérer et utiliser des API puissantes.
Avantages 2.Swagger
Le code change, la documentation change. Avec seulement une petite quantité d'annotations, Swagger peut générer automatiquement une documentation API basée sur le code, ce qui garantit l'actualité de la documentation.
Cross language, prend en charge plus de 40 langues.
Ce que Swagger UI présente est un document API interactif. Nous pouvons essayer l'appel API directement sur la page du document, éliminant ainsi le besoin de préparer des paramètres d'appel complexes.
Vous pouvez également importer des spécifications de document dans des outils associés (tels que Postman, SoapUI), et ces outils créeront automatiquement des tests automatisés pour nous.
Intégrer Swagger dans SpringBoot
1. Construction de l'environnement de base
Commencez par créer un projet SpringBoot de base et importez le démarreur Swagger suivant
<dependency> <groupId> io.springfox </groupId> <artifactId> springfox-boot-starter <artifactId> <version> 3.0.0 </version> </dependency>
Ecrire un contrôleur pour le test
// java 源码 大全 www.fhadmin.org
@RestController
public class HelloController {
@PostMapping (value = "/ hello")
public String hello () {
return "hello";
}
}
Ecrire la classe de configuration Swagger
@Configuration
@EnableOpenApi
Classe publique SwaggerConfig {
}
Exécutez l'adresse d'entrée de démarrage: http: // localhost: 8080 / swagger-ui / index.html
Vous pouvez voir la page de documentation de l'interface Swagger, indiquant que l'environnement de configuration de base est réussi!
Remarque:
l'adresse de la version Swagger3.0 est http: // localhost: 8088 / swagger-ui / index.html, et l'adresse accessible dans la version 2.x est http: // localhost: 8088 / swagger-ui.html
2. Configurer Swagger
Pour configurer Swagger, vous devez d'abord construire son Docketobjet d' instance Bean SwaggerConfig et créer un Docket dans la classe de configuration que vous venez de créer
// java 源码 大全 www.fhadmin.org
@Bean
public Docket docket () {
return new Docket (DocumentationType.OAS_30)
.apiInfo (apiInfo ());
}
Docket(DocumentationType.OAS_30) , Le paramètre que nous choisissons ici est DocumentationType.OAS_30, ceci est la version du document d'interface d'une instance de Swagger, nous sommes ici 3.0, alors choisissez d'utiliser OAS_30, les autres types sont les suivants, correspondant respectivement à la version historique de Swagger
public static final DocumentationType SWAGGER_12 = new DocumentationType ("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType ("swagger", "2.0");
public static final DocumentationType OAS_30 = new DocumentationType ("openApi", "3.0");
La création d'un dossier nécessite la création d'une ApiInfo instance
// Code source Java complet www.fhadmin.org
private ApiInfo apiInfo () {
// Informations sur l'auteur
Contact contact = new Contact ("TIOXY", "https://www.cnblogs.com/tioxy/", "1369773052 @ qq. com ");
retourne le nouveau ApiInfo (
" Document d'interface de Tioxy ",
" Description du projet ",
" 1.0 ",
" https://www.cnblogs.com/tioxy/ ",
contact,
" Apache 2.0 ",
" http: / /www.apache.org/licenses/LICENSE-2.0 ",
nouveau ArrayList ());
}
ApiInfo La fonction principale est de construire les informations de base affichées sur la page de notre document d'interface, présentées à la position suivante
3. Configurer l'interface de numérisation et le commutateur
Lors de la création de Docket, select() configurez l'interface de numérisation à l' aide de méthodes. Le code complet de Docket est le suivant:
// Code source java complet www.fhadmin.org
@Bean
public Docket docket (Environnement environnement) {
// Définit les
profils d' environnement Swagger affichés dev = Profiles.of ("dev");
// Récupère l'environnement du projet
boolean flag = environment.acceptsProfiles (dev);
return new Docket (DocumentationType.OAS_30)
.apiInfo (apiInfo ())
// Configurer le regroupement de documents Api.
groupName ("TIOXY")
// enable () si activer Swagger, la valeur par défaut est true
.enable (flag)
. select ()
// RequestHandlerSelectors, configurez la manière de scanner l'interface
// basePackage spécifie le package à scanner
// any () scanne tout, toutes les interfaces du projet seront analysées
// aucune () ne scanne pas
// withClassAnnotation () scanne les annotations sur la classe
// withMethodAnnotation () scanne les annotations sur
method.apis (RequestHandlerSelectors.basePackage ("com.tioxy.controller"))
// chemins () filtre un
chemin.paths (PathSelectors.any ())
.build ();
}
groupName("TIOXY"): Représente le nom de cette instance de Docket, c'est-à-dire le nom de l'instance sélectionnée dans le coin supérieur droit de la page du document d'interface. En développement réel, nous développons par plusieurs personnes, ce qui correspond à plusieurs instances de Docketenable(flag):enable()S'il faut activer Swagger, la valeur par défaut est true
Ce que nous utilisons ici est la configuration dynamique de l'activation de Swagger, par le biais Environment pour obtenir le nom de l'environnement de projet en cours d'exécution à ce moment, si c'est le cas dev, définir un indicateur pour définir dynamiquement s'il faut activer
4. Configuration de la classe d'entité
Créer une nouvelle classe d'entité utilisateur
@ApiModel ("User entity")
public class User {
@ApiModelProperty ("Username")
public String username;
@ApiModelProperty ("Password")
public String password;
}
Tant que cette entité est dans la valeur de retour de l'interface de demande (même s'il s'agit d'un générique), elle peut être mappée à l'élément d'entité:
@RequestMapping ("/ getUser")
public User getUser () {
return new User ();
}
5. Notes communes
Nous pouvons également ajouter des notes à l'interface, afin que nous puissions expliquer les informations de l'interface dans le document d'interface, telles que la fonction de l'interface, la description des paramètres, etc., pour la commodité de l'appelant
| Annotation Swagger | Brève description |
|---|---|
| @Api (tags = "description du module xxx") | Agir sur la classe de module |
| @ApiOperation ("Description de l'interface xxx") | Agir sur les méthodes d'interface |
| @ApiModel ("description xxxPOJO") | Agir sur la classe de modèle: comme VO, BO |
| @ApiModelProperty (value = "xxx property description", hidden = true) | Agir sur les méthodes de classe et les propriétés, hidden est défini sur true pour masquer la propriété |
| @ApiParam ("Description du paramètre xxx") | Agir sur les paramètres, méthodes et champs, similaire à @ApiModelProperty |