Comment SpringBoot intègre-t-il Swagger ?

Spring Boot est un framework open source léger basé sur le framework Spring. Son émergence simplifie grandement la construction et le développement d'applications Spring. Dans le processus de développement, la documentation de l'interface est un élément très important. Elle permet non seulement aux développeurs de visualiser et de comprendre les fonctions et les paramètres de l'interface, mais aide également les développeurs front-end et back-end à travailler ensemble pour améliorer l'efficacité du développement.

1. À propos de Swagger

Swagger est une spécification et un ensemble d'outils pour les documents d'interface RESTful. Son objectif est d'unifier le format et les spécifications des documents d'interface RESTful. Dans le processus de développement, la documentation de l'interface est un élément très important. Elle permet non seulement aux développeurs de visualiser et de comprendre les fonctions et les paramètres de l'interface, mais aide également les développeurs front-end et back-end à travailler ensemble pour améliorer l'efficacité du développement. Spring Boot peut intégrer Swagger pour générer automatiquement des documents d'interface. En utilisant des annotations pour décrire les interfaces, Swagger peut générer automatiquement des documents d'interface.

2. Installation de Swagger

1. Téléchargez Swagger

Le site officiel de Swagger est https://swagger.io/, où nous pouvons télécharger la dernière version de Swagger.

2. Installez Swagger

Décompressez simplement le Swagger téléchargé dans le répertoire spécifié. Ce processus d'installation est assez simple. Dans le répertoire décompressé, nous pouvons trouver la page swagger-ui.html, qui est l'interface UI de Swagger.

3. Utilisation de Swagger

1. Écriture d'interfaces

Lors de l'écriture d'interfaces, nous devons utiliser les annotations Swagger pour décrire les informations de l'interface. Les annotations couramment utilisées incluent :

• @Api : utilisé pour décrire la classe ou l'interface de l'interface

• @ApiOperation : utilisé pour décrire les méthodes de l'interface

• @ApiParam : utilisé pour décrire les paramètres de l'interface

• @ApiModel : utilisée pour décrire le modèle de données

• @ApiModelProperty : utilisée pour décrire les propriétés du modèle de données

Par exemple, nous écrivons une interface simple :

@RestController
@Api(tags = "用户接口")
public class UserController {
 
    @GetMapping("/user/{id}")
    @ApiOperation(value = "根据 ID 获取用户信息")
    public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) {
        // 根据 ID 查询用户信息
    }
}

Dans ce qui précède code, @Api signifie que la classe est une interface utilisateur, @ApiOperation indique que la méthode est une interface permettant d'obtenir des informations utilisateur, @ApiParam indique que le paramètre est un ID utilisateur et @PathVariable indique que le paramètre est un paramètre de chemin.

2. Activer Swagger

Dans Spring Boot, nous pouvons activer Swagger en ajoutant des dépendances liées à Swagger.
Nous pouvons ajouter les dépendances suivantes dans le fichier pom.xml :

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

Dans Spring Boot, nous devons également ajouter une classe de configuration pour configurer Swagger. Le code de la classe de configuration est le suivant :

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
}

Dans le code ci-dessus, @Configuration indique que la classe est une classe de configuration, et @EnableSwagger2 indique que Swagger est activé. Dans la méthode api(), nous configurons le chemin du package analysé via la méthode `select(), configurons le chemin d'accès de l'interface via la méthode paths() et configurons les informations associées du document d'interface via la méthode apiInfo().

3. Afficher le document d'interface

Après avoir démarré l'application Spring Boot, nous pouvons visiter http://localhost:8080/swagger-ui.html dans le navigateur pour afficher le document d'interface. Dans la page de l'interface utilisateur Swagger, nous pouvons voir toutes les informations sur l'interface, y compris le nom de l'interface, la méthode de requête, le chemin de la requête, les paramètres de la requête, les paramètres de réponse, etc.

4. Utilisation avancée de Swagger

1. Décrire le modèle de données

Nous pouvons utiliser les annotations @ApiModel et @ApiModelProperty pour décrire le modèle de données et les propriétés. Par exemple, nous pouvons écrire une classe User et utiliser @ApiModel et @ApiModel 和 @ApiModelProperty 注解来描述数据模型和属性。例如，我们可以编写一个 User 类，并在类上使用 @ApiModel 和

@ApiModelProperty 注解来描述该数据模型：

@ApiModel(description = "用户信息")
public class User {
 
    @ApiModelProperty(value = "用户 ID", example ="1") 
    private Long id;

	@ApiModelProperty(value = "用户名", example = "张三")
	private String username;

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

	// 省略 getter 和 setter 方法
}

在上面的代码中，@ApiModel 表示该类是一个数据模型，@ApiModelProperty 表示该属性是数据模型的一个属性，value 属性表示属性的描述，example 属性表示属性的示例值。

2、描述枚举类型

我们可以使用 @ApiModel 和 @ApiModelProperty

@ApiModel(description = "性别") public enum Gender {

@ApiModelProperty(value = "男")
MALE,

@ApiModelProperty(value = "女")
FEMALE;
}

sur la classe, @ApiModel indique que la classe est un modèle de données, @ApiModelProperty indique que l'attribut est un attribut du modèle de données. , et l'attribut value représente une description de l'attribut, et l'attribut example représente un exemple de valeur de l'attribut.

2. Décrire les types d'énumération

Nous pouvons utiliser les annotations @ApiModel et @ApiModelProperty pour décrire les types d'énumération. Par exemple, nous pouvons écrire un type d'énumération Gender et utiliser l'annotation @ApiModelProperty sur la valeur d'énumération pour décrire la valeur d'énumération :

@GetMapping("/user/{id}")
@ApiOperation(value = "根据 ID 获取用户信息") 
@ApiResponses({ @ApiResponse(code = 200, message = "请求成功", response = User.class), 
@ApiResponse(code = 404, message = "用户不存在") }) 
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) 
{ 
	// 根据 ID 查询用户信息 
}

Dans le code ci-dessus, @ApiModel indique que le type d'énumération est une énumération qui décrit le type d'énumération de genre, @ApiModelProperty indique que la valeur d'énumération est une valeur d'énumération qui décrit les hommes ou une valeur d'énumération qui décrit les femmes.

3. Décrire les paramètres de réponse

Nous pouvons utiliser les annotations @ApiResponses et @ApiResponse pour définir les paramètres de réponse de l'API. Par exemple, nous pouvons écrire une méthode getUserById() et utiliser les annotations @ApiResponses et @ApiResponse sur la méthode pour décrire les paramètres de réponse de la méthode :

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(Arrays.asList(
                        new ParameterBuilder()
                                .name("Authorization")
                                .description("授权")
                                .modelRef(new ModelRef("string"))
                                .parameterType("header")
                                .required(false)
                                .build()
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

Dans le code ci-dessus, @ApiResponses représente les paramètres de réponse de la méthode, @ ApiResponse Indique la description des paramètres de réponse, l'attribut code indique le code de réponse, l'attribut message indique le message de réponse et l'attribut de réponse indique le modèle de données de réponse.

5. Utilisation avancée de Swagger

1. Configurer les paramètres globaux🎜🎜En utilisant la méthode globalOperationParameters(), nous pouvons configurer les paramètres globaux dans la classe de configuration. Nous pouvons autoriser en configurant un paramètre d'autorisation global🎜

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Arrays.asList(
                        new ApiKey("Bearer", "Authorization", "header")
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

🎜Dans le code ci-dessus, nous configurons un paramètre d'autorisation global pour l'autorisation via la méthode globalOperationParameters(). 🎜

2、配置安全协议

通过在配置类中调用 securitySchemes() 方法，我们能够进行安全协议的配置。举个例子，可以设置 Bearer Token 作为安全协议

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Arrays.asList(
                        new ApiKey("Bearer", "Authorization", "header")
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

在上面的代码中，我们通过 securitySchemes() 方法来配置一个 Bearer Token 安全协议。

3、配置安全上下文

使用 securityContexts() 方法配置安全上下文是配置类中的一种可选方法。举个例子，我们可以设置一个安全上下文来在Swagger UI中展示认证按钮：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Arrays.asList(
                        new ApiKey("Bearer", "Authorization", "header")
                ))
                .securityContexts(Collections.singletonList(
                        SecurityContext.builder()
                                .securityReferences(Collections.singletonList(
                                        new SecurityReference("Bearer", new AuthorizationScope[0])
                                ))
                                .build()
                ))
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .version("1.0.0")
                .build();
    }
 
}

在上面的代码中，我们通过 securityContexts() 方法来配置一个安全上下文，用于在 Swagger UI 中显示认证按钮。

4、配置忽略参数

在API文档中，可能有些参数包含敏感信息，因此需要保护这些信息不被公示。我们可以使用 @ApiIgnore 注解来忽略这些参数。在 User 类中，我们可以使用 @ApiIgnore 注解来排除密码参数

@ApiModel(description = "用户信息")
public class User {
 
    @ApiModelProperty(value = "用户 ID", example = "1")
    private Long id;
 
    @ApiModelProperty(value = "用户名", example = "张三")
    private String username;
 
    @ApiModelProperty(hidden = true)
    @ApiIgnore
    private String password;
 
    // 省略 getter 和 setter 方法
}

在上面的代码中，@ApiModelProperty(hidden = true) 表示该参数是隐藏的，@ApiIgnore 表示忽略该参数。

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!