Extrait des notes SpringBoot en Java à la station B Kuangshenshuo, le
maître de la porte de transmission SpringBoot UP est très agréable, les cours sont vifs et vifs, bienvenue au support.

Introduction

Je pense que le développement front-end et back-end a été plus ou moins torturé par les documents d'interface. Le front-end se plaint souvent que les documents d'interface donnés par le back-end ne correspondent pas à la situation réelle. Le backend estime que l'écriture et la maintenance des documents d'interface consomment beaucoup d'énergie et qu'il est souvent trop tard pour les mettre à jour. En fait, que le frontal appelle le back-end ou que le back-end appelle le back-end, nous attendons tous un bon document d'interface. Mais ce document d'interface est comme des commentaires pour les programmeurs. Ils se plaignent souvent que le code écrit par d'autres n'écrit pas de commentaires, mais lorsqu'ils écrivent du code par eux-mêmes, la chose la plus ennuyeuse est d'écrire des commentaires. Par conséquent, il ne suffit pas de normaliser tout le monde par la seule coercition : au fur et à mesure que le temps passe et que la version est itérée, la documentation de l'interface ne peut souvent pas suivre le code.

solution

Définissez d'abord le schéma [les grandes lignes du plan], et suivez la dernière API en temps réel pour réduire les risques d'intégration

fanfaronnade

Reconnu comme le framework d'API le plus populaire au monde
Générateur automatique en ligne de documents Restful Api => 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 langages (tels que : Java, PHP, etc.)
Site officiel : https://swagger.io/

SpringBoot intègre Swagger

Ajouter une dépendance Mavex

<!-- 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>

Configurer Swagger

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

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配 置
public class SwaggerConfig {
    
    
    //配置了swagger的Docket的bean实例
  @Bean //配置docket以配置Swagger具体参数
public Docket docket() {
    
    
   return new Docket(DocumentationType.SWAGGER_2);
   }
}

2. Les informations sur le document peuvent être configurées via l'attribut apiInfo()

    //配置文档信息
    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<>()// 扩展
        );
    }

Configurer l'interface de numérisation

1. Lors de la création d'un dossier, configurez comment analyser l'interface via la méthode select().

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

2. Redémarrez le test du projet. Étant donné que nous configurons l'interface d'analyse 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 d'analyse. l'interface. Ici, commentez toutes les configurations Way:

any() // Analyser tout, toutes les interfaces du projet seront analysées vers
none() // Ne pas analyser les interfaces
// Analyser les annotations sur les méthodes, telles que withMethodAnnotation(GetMapping.class) analyse uniquement les requêtes get
withMethodAnnotation(final Class < ? étend Annotation> annotation)
// analyse les annotations sur la classe, telles que .withClassAnnotation (Controller.class) analyse uniquement les interfaces dans les classes avec des annotations de contrôleur
withClassAnnotation (final Class <? étend Annotation> annotation)
basePackage (final String basePackage) // Scanne l'interface selon le chemin du package

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

@Bean
public Docket docket() {
    
    
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

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

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

Configurer le regroupement d'API

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

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

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

Configuration de la classe d'entité

1. Créer une nouvelle classe d'entité

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

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

insérez la description de l'image ici

Remarques communes

Annotations fanfaronnes	brève description
@Api(tags = "description du module xxx")	agir sur la classe du module
@ApiOperation("description de l'interface xxx")	agir sur la méthode d'interface
@ApiModel("xxxPOJO Description")	Agir sur la classe du modèle : comme VO, BO
@ApiModelProperty(valeur = "description de l'attribut xxx", caché = vrai)	Agit sur les méthodes et les propriétés de la classe, la définition de hidden sur true peut masquer la propriété
@ApiParam("description du paramètre xxx")	Agit sur les paramètres, les méthodes et les champs, similaire à @ApiModelProperty

SpringBoot : intégration de Swagger