Comment utiliser l'outil de gestion d'interface intégré SpringBoot Swagger

1. Introduction à Swagger

Swagger est une série d'outils API RESTful, grâce à Swagger, vous pouvez obtenir un document interactif du projet, la génération automatique du SDK client et d'autres fonctions.

L'objectif de Swagger est de définir une interface standard indépendante du langage pour les API REST afin que les personnes et les ordinateurs puissent la découvrir et la comprendre sans voir le code source ou la documentation ou sans échouer dans la détection du trafic réseau de divers services. Lorsque les services sont définis via Swagger, les consommateurs peuvent interagir avec des services distants avec une petite quantité de logique de mise en œuvre.

2. Springboot intègre swagger

L'idée d'utiliser Spring Boot pour intégrer Swagger est d'utiliser des annotations pour marquer les informations qui doivent être affichées dans le document API. Swagger générera le document API correspondant en fonction des annotations marquées. dans le projet. Swagger est connu comme l'outil API le plus populaire au monde. Il fournit une solution complète pour la gestion des API. Les facteurs à prendre en compte pour la gestion des documents API sont essentiellement abordés ici.

1. Ajouter des coordonnées swagger

Spring Boot intégrant Swagger 3 est très simple, il vous suffit d'introduire des dépendances et d'effectuer une configuration de base.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. Implémentation de Swagger Helloword

2.1. Créer un projet Springboot

Ajoutez l'annotation @EnableOpenApi à la classe de démarrage pour activer la fonction de document de l'API swagger

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
    }

}

2.2. Écrire une interface

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
public class SwaggerController {
    @GetMapping ("hello")
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2.3. Adresse d'accès

http://localhost:8080/swagger-ui/index.html

3. Annotations de configuration couramment utilisées

Swagger utilise des annotations pour indiquer que l'interface générera des documents, y compris le nom de l'interface, la méthode de requête, les paramètres, les informations de retour, etc.

1, Api annotations et ApiOperation annotations

• @Api

est utilisé sur une classe, indiquant qu'il s'agit d'une ressource swagger @API a deux attributs : valeur et balises.

Les documents API générés seront classés en fonction des balises. Pour parler franchement, les documents d'interface générés par toutes les interfaces de ce contrôleur seront sous la liste des balises ; si les balises ont plusieurs valeurs, plusieurs listes seront générées, chaque liste affichée ; toutes les interfaces

value fonctionne comme des balises, mais ne peut pas avoir plusieurs valeurs

语法:
  @Api(tags = "用户操作")
  或
  @Api(tags = {"用户操作","用户操作2"})

• @ApiOperation

est utilisé sur les méthodes pour représenter le fonctionnement d'une requête http

语法:
    @ApiOperation(value = "", 
                  notes = "", 
                  response = )
属性说明：
  value：方法说明标题
  notes：方法详细描述
  response：方法返回值类型

Cas : utilisez @Api et @ApiOperation pour générer des documents API

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2, ApiImplicitParams les annotations et ApiImplicitParam

@ApiImplicitParams les annotations et @ApiImplicitParam sont utilisées pour les paramètres non-objet dans les méthodes (utilisées lorsque les paramètres sont liés aux types simples. ) pour expliquer

语法:
@ApiImplicitParams(value = {
     @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
})

属性说明：
    name:形参名称
    value:形参的说明文字
    type:形参类型
    required:该参数是否必须  true|false
    paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header 
        path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
    	query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
    	header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
    	form 不常用.
    defaultValue :参数默认值

Remarque : L'attribut name de @ApiImplicitParam doit faire écho à la valeur de @RequestParam ou @PathVariable.

Cas : utilisez l'annotation @ApiImplicitParams et @ApiImplicitParam pour décrire les paramètres de la méthode

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    @ApiImplicitParams(value ={
            @ApiImplicitParam(name="param1",
                    value = "参数名1",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值1" ),
            @ApiImplicitParam(name="param2",
                    value = "参数名2",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值2" )
    })
    public String hello(String param1,String param2) {
        return "hello swagger"+" param1为:"+param1+"param2为"+param2;
    }
}

3, l'annotation ApiModel et ApiModelProperty

• @ApiModel

  est utilisée sur les classes d'entités pour indiquer la description de la réception des paramètres de classe. instructions dans les classes d’entités.

@ApiModel("用户类")
@Data
public class Users {

    @ApiModelProperty(value = "编码：主键")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

}

4. Les annotations ApiResponse et ApiResponses

@ApiResponses et @ApiResponse sont marquées sur la méthode Controller pour décrire la réponse de la requête HTTP

/**
     * 添加用户
     *
     * @param user
     * @return
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
    @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
            	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
    public ResponseResult<Void> addUser(@RequestBody User user) {
        //获得生成的加密盐
        user.setSalt(SaltUtils.getSalt());
        int n = userService.addUser(user);
        if (n > 0) {
            return new ResponseResult<Void>(200, "添加成功");
        }
        return new ResponseResult<Void>(500, "添加失败");
    }

5 Créez la classe de configuration SwaggerConfig

Dans SwaggerConfig, ajoutez deux méthodes dans. : (L'une des méthodes est une préparation auxiliaire pour l'autre méthode) La méthode

api() utilise @Bean, initialisée au démarrage, et renvoie l'instance Docket (objet récapitulatif de l'API Swagger). apis(RequestHandlerSelectors .basePackage("xxx.yyy.zzz")) spécifie le chemin du package qui doit être analysé. Seule la classe Controller sous ce chemin générera automatiquement le document API Swagger. La configuration de la méthode

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置类
 */
@Configuration  //项目启动时加载此类
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("com.lps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("阿水的项目接口文挡")
                .description("阿水的 Project Swagger2 UserService Interface")  //说明信息
                .termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
                .version("1.0")  //文档版本
                .build();
    }
}

apiInfo() est relativement importante. Les informations de base affichées sur la page de configuration principale incluent le titre, la description, la version, les conditions d'utilisation, etc. Si vous regardez le code source de la classe ApiInfo, vous trouverez également plus de configurations telles que la prise en charge des licences. 4. Springsecurity intègre swagger

4.1, configure l'adresse publiée

  http.authorizeRequests().antMatchers( "/swagger-ui.html",
                "/swagger-ui/*",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**").permitAll()
                .anyRequest().authenticated();

4.2 et remplace l'interface utilisateur

L'ensemble du processus ci-dessus est terminé, mais la page du document d'interface générée n'est en fait pas appréciée par Beaucoup de gens pensent que cela ne convient pas à une utilisation chinoise, certains maîtres proposent donc d'autres pages de test d'interface utilisateur. Cette page est encore largement utilisée.

Importez les dépendances suivantes, redémarrez le projet et visitez l'adresse : http://localhost:8080/doc.html

	<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!