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.
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.
Le site officiel de Swagger est https://swagger.io/, où nous pouvons télécharger la dernière version de 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.
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.
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().
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.
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 属性表示属性的示例值。
我们可以使用 @ApiModel 和 @ApiModelProperty
@ApiModel(description = "性别") public enum Gender {
@ApiModelProperty(value = "男")
MALE,
@ApiModelProperty(value = "女")
FEMALE;
}@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 查询用户信息
}@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();
}
}@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 作为安全协议
@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 安全协议。
使用 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 中显示认证按钮。
在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!
Étapes de création du projet SpringBoot
Comment utiliser Swagger
Quelle est la différence entre j2ee et springboot
La différence entre xdata et data
Comment supprimer des pages vierges dans Word
description de la page de référencement
Comment activer le service de connexion secondaire
Hongmeng OS compte-t-il comme Android ?
![[Web front-end] Démarrage rapide de Node.js](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
