溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務條款》
您好，登錄后才能下訂單哦！
本文小編為大家詳細介紹“SpringBoot整合Swagger的方法是什么”，內容詳細，步驟清晰，細節處理妥當，希望這篇“SpringBoot整合Swagger的方法是什么”文章能幫助大家解決疑惑，下面跟著小編的思路慢慢深入，一起來學習新知識吧。
Spring Boot 是一個基于 Spring 框架的輕量級開源框架，它的出現極大地簡化了 Spring 應用的搭建和開發。在開發過程中，接口文檔是非常重要的一環，它不僅方便開發者查看和理解接口的功能和參數，還能幫助前后端開發協同工作，提高開發效率。
Swagger 是一個 RESTful 接口文檔的規范和工具集，它的目標是統一 RESTful 接口文檔的格式和規范。在開發過程中，接口文檔是非常重要的一環，它不僅方便開發者查看和理解接口的功能和參數，還能幫助前后端開發協同工作，提高開發效率。在 Spring Boot 中，我們可以通過集成 Swagger 來實現接口文檔的自動生成。Swagger 通過注解來描述接口，然后根據這些注解自動生成接口文檔。
Swagger 的官方網站是 https://swagger.io/，我們可以在這里下載最新版本的 Swagger。
安裝 Swagger 非常簡單，只需要將下載的 Swagger 解壓到指定目錄即可。在解壓后的目錄中，我們可以找到 swagger-ui.html 頁面，這個頁面就是 Swagger 的 UI 界面。
在編寫接口時，我們需要使用 Swagger 的注解來描述接口信息。常用的注解包括：
@Api：用于描述接口的類或接口
@ApiOperation：用于描述接口的方法
@ApiParam：用于描述接口的參數
@ApiModel：用于描述數據模型
@ApiModelProperty：用于描述數據模型的屬性
例如，我們編寫一個簡單的接口：
@RestController
@Api(tags = "用戶接口")
public class UserController {
@GetMapping("/user/{id}")
@ApiOperation(value = "根據 ID 獲取用戶信息")
public User getUserById(@ApiParam(value = "用戶 ID", required = true) @PathVariable Long id) {
// 根據 ID 查詢用戶信息
}
}在上面的代碼中，@Api表示該類是一個用戶接口，@ApiOperation 表示該方法是獲取用戶信息的接口，@ApiParam 表示該參數是用戶 ID，@PathVariable 表示該參數是路徑參數。
在 Spring Boot 中，我們可以通過添加 Swagger 相關的依賴來啟用 Swagger。
我們可以在 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>
在 Spring Boot 中，我們還需要添加配置類來配置 Swagger。配置類的代碼如下：
@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();
}
}在上面的代碼中，@Configuration 表示該類是一個配置類，@EnableSwagger2 表示啟用 Swagger。在 api() 方法中，我們通過 `select() 方法配置掃描的包路徑，paths() 方法配置接口的訪問路徑，apiInfo() 方法配置接口文檔的相關信息。
啟動 Spring Boot 應用后，我們可以在瀏覽器中訪問 http://localhost:8080/swagger-ui.html 來查看接口文檔。在 Swagger UI 頁面中，我們可以看到所有的接口信息，包括接口名稱、請求方式、請求路徑、請求參數、響應參數等。
我們可以使用 @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 注解來描述枚舉類型。例如，我們可以編寫一個 Gender 枚舉類型，并在枚舉值上使用 @ApiModelProperty 注解來描述該枚舉值：
@ApiModel(description = "性別") public enum Gender {
@ApiModelProperty(value = "男")
MALE,
@ApiModelProperty(value = "女")
FEMALE;
}在上面的代碼中，@ApiModel 表示該枚舉類型是一個描述性別的枚舉類型，@ApiModelProperty 表示該枚舉值是描述男性的枚舉值或描述女性的枚舉值。
我們可以使用 @ApiResponses 和 @ApiResponse 注解來描述接口的響應參數。例如，我們可以編寫一個 getUserById() 方法，并在方法上使用 @ApiResponses 和 @ApiResponse 注解來描述該方法的響應參數：
@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 查詢用戶信息
}在上面的代碼中，@ApiResponses 表示該方法的響應參數，@ApiResponse 表示該響應參數的描述，code 屬性表示響應碼，message 屬性表示響應消息，response 屬性表示響應的數據模型。
我們可以在配置類中使用 globalOperationParameters() 方法來配置全局參數。例如，我們可以配置一個全局的 Authorization 參數，用于授權：
@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();
}
}在上面的代碼中，我們通過 globalOperationParameters() 方法來配置一個全局的 Authorization 參數，用于授權。
我們可以在配置類中使用 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 中顯示認證按鈕。
在接口中，有些參數可能是敏感信息，我們不希望在接口文檔中顯示。我們可以使用 @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的方法是什么”文章已經介紹完畢，想要掌握這篇文章的知識點還需要大家自己動手實踐使用過才能領會，如果想了解更多相關內容的文章，歡迎關注億速云行業資訊頻道。
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
