Spring Boot 是一個基於 Spring 框架的輕量級開源框架，它的出現極大地簡化了 Spring 應用的建構和開發。在開發過程中，介面文件是非常重要的一環，它不僅方便開發者查看和理解介面的功能和參數，還能幫助前後端開發協同工作，提高開發效率。
Swagger 是一個 RESTful 介面文件的規格和工具集，它的目標是統一 RESTful 介面文件的格式和規格。在開發過程中，介面文件是非常重要的一環，它不僅方便開發者查看和理解介面的功能和參數，還能幫助前後端開發協同工作，提高開發效率。 Spring Boot 可以整合 Swagger 來自動產生介面文件。透過使用註解描述接口，Swagger能夠自動產生接口文件。
Swagger 的官方網站是https://swagger.io/，我們可以在這裡下載最新版本的Swagger 。
解壓縮下載的 Swagger 到指定目錄即可，這個安裝過程相當簡單。在解壓縮後的目錄中，我們可以找到 swagger-ui.html 頁面，這個頁面就是 Swagger 的 UI 介面。
在寫介面時，我們需要使用 Swagger 的註解來描述介面資訊。常用的註解包括：
@Api：用來描述介面的類別或介面
@RestController
@Api(tags = "用户接口")
public class UserController {
@GetMapping("/user/{id}")
@ApiOperation(value = "根据 ID 获取用户信息")
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) {
// 根据 ID 查询用户信息
}
}我們可以在 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>@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();
}
}@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 註解來描述枚舉類型。例如，我們可以編寫一個Gender 枚舉類型，並在枚舉值上使用@ApiModelProperty 註解來描述該枚舉值：
@ApiModel(description = "性别") public enum Gender {
@ApiModelProperty(value = "男")
MALE,
@ApiModelProperty(value = "女")
FEMALE;
}@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();
}
}通过在配置类中调用 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 表示忽略该参数。
以上是SpringBoot整合Swagger的方法是什麼的詳細內容。更多資訊請關注PHP中文網其他相關文章！
