springboot-13-swagger

cible d'apprentissage:

• Comprendre le concept et la fonction de Swagger

• Maîtriser l'intégration de Swagger dans le projet pour générer automatiquement la documentation API

一 、 Swagger

1. Concept

Swagger est un framework standardisé et complet pour générer, décrire, appeler et visualiser des services Web RESTful. L'objectif global est de mettre à jour le client et le système de fichiers à la même vitesse que le serveur. Les méthodes de fichier, 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.

2. Caractéristiques

• Connu comme le framework d'API le plus populaire au monde

• Restful Api document online automatic generator => Le document API et la définition de l'API sont mis à jour de manière synchrone

• Exécutez directement, testez l'API en ligne

• Prend en charge plusieurs langues (telles que: Java, PHP, etc.)

• Site officiel: https://swagger.io/

Deux, swagger intégré à Springboot

1. Créez un nouveau projet springboot, ajoutez des dépendances Web
2. Importez les dépendances requises Swagger

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3. Pour utiliser Swagger, nous devons écrire une classe de configuration-SwaggerConfig pour configurer Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
    
      
}

4. Visitez le test: http: // localhost: 8080 / swagger-ui.html, vous pouvez voir l'interface de swagger;

1. Configurer swagger

1. Le bean d'instance Swagger est Docket, donc configurez le Swaggger en configurant l'instance Docket.

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
    
    
   return new Docket(DocumentationType.SWAGGER_2);
}

2. apiInfo()Les informations du document peuvent être configurées via les propriétés

//配置文档信息
private ApiInfo apiInfo() {
    
    
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

3. L'instance de Docket est associée à apiInfo ()

@Bean
public Docket docket() {
    
    
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4, redémarrez le projet, accédez à l' http://localhost:8080/swagger-ui.htmleffet de test facie;

2. Configurez l'interface de numérisation

1. Lors de la construction de Docket, select()configurez comment analyser l'interface via la méthode.

@Bean
public Docket docket() {
    
    
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
      .build();
}

2. Redémarrez le test du projet. Puisque nous avons configuré pour analyser l'interface en fonction du chemin du package, nous ne pouvons voir qu'une seule classe.

3. En plus de configurer l'interface d'analyse via le chemin du package, vous pouvez également configurer d'autres méthodes pour scannez l'interface. Voici une note sur toutes les configurations en cours:

//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 指定要扫描的包
//any() 扫描全部
//none() 不扫描
//withMethodAnnotation 扫描方法上的注解，参数是注解的反射对象（GetMapping.class）
//withClassAnnotation 扫描类上的注解（RestController.class）

4. De plus, nous pouvons également configurer le filtrage de l'analyse d'interface:

    @Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
                .paths(PathSelectors.ant("/kuang/**")) //请求中有kuang的
                .build();
    }

3. Configurer le commutateur Swagger

1. enable()Configurez s'il faut activer swagger via la méthode. S'il est faux, swagger ne sera pas accessible dans le navigateur.

@Bean
public Docket docket(Environment environment){
    
    

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
            .paths(PathSelectors.ant("/hello"))
            .build();
}

2. Comment configurer dynamiquement swagger pour qu'il s'affiche lorsque le projet est dans l'environnement de test et de développement, mais pas lorsqu'il est dans l'environnement de production?

@Bean
public Docket docket(Environment environment) {
    
    
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean flag = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(flag) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

Springboot change l'environnement d'utilisation, s'il est Profiles.of("dev", "test")ici, il sera affiché normalement, s'il n'est pas ici, il ne peut pas être utilisé.

4. Configurer le regroupement d'API

1. Si aucun groupe n'est configuré, la valeur par défaut est la valeur par défaut. groupName()Le regroupement peut être configuré par méthode

@Bean
public Docket docket(Environment environment) {
    
    
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

2. Comment 配置多个分组? Pour configurer plusieurs groupes, il vous suffit de configurer plusieurs dossiers.

@Bean
public Docket docket(Environment environment){
    
    

    Profiles of = Profiles.of("dev", "test");
    boolean flag = environment.acceptsProfiles(of);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("狂神")
            .enable(flag)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
            .paths(PathSelectors.ant("/hello"))
            .build();
}

@Bean
public Docket docket2(){
    
    
    return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}

@Bean
public Docket docket3(){
    
    
    return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}

5. Configurer les informations d'annotation

Annotation sur la classe d'entité

@ApiModel("用户实体类")
public class User {
    
    
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("密码")
    public String password;
}

S'il y a des classes d'entité dans la valeur de retour de la méthode, elle sera analysée

@GetMapping("/user")
public User hello2(){
    
    
    return new User();
}

Annotation de méthode

@ApiOperation("测试方法")
@GetMapping("/test")
public String hello3(@ApiParam("用户名") String name){
    
    
    return name;
}

Annotations couramment utilisées
@Api(tags = "xxx模块说明") : Agir sur la classe du module
@ApiOperation("xxx接口说明"): Agir sur la méthode d'interface
@ApiModel("xxxPOJO说明"): Agir sur la classe du modèle: comme VO, BO
@ApiModelProperty(value = "xxx属性说明",hidden = true): Agir sur les méthodes et les attributs, mettre hidden à true pour masquer l'attribut
@ApiParam("xxx参数说明"): Agir sur les paramètres, les méthodes et les champs , Similaire à @ApiModelProperty

Par rapport à la méthode traditionnelle de test des interfaces Postman ou Curl, l'utilisation de swagger est simplement une opération insensée. Elle ne nécessite pas de documentation supplémentaire (bien écrit est un document en soi) et est moins sujette aux erreurs. Entrez simplement les données et cliquez sur Exécuter. Si vous coopérez à nouveau Framework d'automatisation, on peut dire qu'il n'y a fondamentalement pas besoin d'opération humaine.

Swagger est un excellent outil, et maintenant de nombreuses petites et moyennes entreprises Internet en Chine l'utilisent. Par rapport à la manière traditionnelle de produire d'abord les documents d'interface Word, puis de les tester, il est évidemment plus conforme au marché actuel du développement itératif rapide. . Bien sûr, je voudrais rappeler à tout le monde de ne pas oublier de fermer Swagger dans l'environnement formel. Premièrement, pour des raisons de sécurité, il peut également économiser la mémoire d'exécution.

6. Autres skins

1. 默认Visitehttp://localhost:8080/swagger-ui.html

<dependency> 
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2. bootstrap-uiVisitehttp://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3. Layui-uiVisitehttp://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4. mg-uiVisitehttp://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>