溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務條款》
您好，登錄后才能下訂單哦！
小編這次要給大家分享的是Spring Boot如何整合swagger，文章內容豐富，感興趣的小伙伴可以來了解一下，希望大家閱讀完這篇文章之后能夠有所收獲。
Swagger的介紹
你可能嘗試過寫完一個接口后，自己去創建接口文檔，或者修改接口后修改接口文檔。多了之后，你肯定會發生一個操作，那就是忘記了修改文檔或者創建文檔（除非你們公司把接口文檔和寫接口要求得很緊密😓忘記寫文檔就扣工資？，否則兩個分離的工作總是有可能遺漏的）。而swagger就是一個在你寫接口的時候自動幫你生成接口文檔的東西，只要你遵循它的規范并寫一些接口的說明注解即可。
優點與缺點
優點：
缺點：
上面的缺點好像寫的有點多，你可能會覺得swagger這個坑有點大。但其實主要是規范問題，而規范問題有時候又會提高你的代碼規范性，這個就見仁見智了，你以前可能什么接口的參數都使用一個類，而現在swagger要求你分開后，某種層次上提高了你的代碼規范性。
注：以下代碼示例基于Spring Boot。完整代碼可以參考：swagger-demo
添加swagger
這里先講添加swagger，也就是先整合進來，至于怎么使用，下面的“場景”中再講解。
1.添加依賴包：
注意，這里的前提是已經導入了spring boot的web包。
<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>
2.配置Swagger:
要使用swagger，我們必須對swagger進行配置，我們需要創建一個swagger的配置類，比如可以命名為SwaggerConfig.java
package com.example.config;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration // 標明是配置類
@EnableSwagger2 //開啟swagger功能
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2
// .groupName("分布式任務系統") // 如果配置多個文檔的時候，那么需要配置groupName來分組標識
.apiInfo(apiInfo()) // 用于生成API信息
.select() // select()函數返回一個ApiSelectorBuilder實例,用來控制接口被swagger做成文檔
.apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定掃描哪個包下的接口
.paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔，可以配置這里
.build();
}
/**
* 用于定義API主界面的信息，比如可以聲明所有的API的總標題、描述、版本
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XX項目API") // 可以用來自定義API的主標題
.description("XX項目SwaggerAPI管理") // 可以用來描述整體的API
.termsOfServiceUrl("") // 用于定義服務的域名
.version("1.0") // 可以用來定義版本。
.build(); //
}
}3.測試
運行我們的Spring Boot項目，（我默認是8080端口，如果你不一樣，請注意修改后續的url），訪問http://localhost:8080/swagger-ui.html
然后你就可以看到一個如下的界面，由于我們暫時沒有配置接口數據，所以下面顯示No operations defined in spec!
下面我們將介紹如何定義接口，以及在swagger UI界面中的內容。
場景：
定義接口組
接口有時候應該是分組的，而且大部分都是在一個controller中的，比如用戶管理相關的接口應該都在UserController中，那么不同的業務的時候，應該定義/劃分不同的接口組。接口組可以使用@Api來劃分。
比如：
@Api(tags = "角色管理") // tags：你可以當作是這個組的名字。
@RestController
public class RoleController {
}和
@Api(tags = "用戶管理") // tags：你可以當作是這個組的名字。
@RestController
public class UserController {
}你也可以理解成基于tags來分組，就好像一些文章里面的標簽一樣，使用標簽來分類。
如果這個Controller下（接口組）下面沒有接口，那么在swagger ui中是不會顯示的，如果有的話就會這樣顯示：
定義接口
使用了@Api來標注一個Controller之后，如果下面有接口，那么就會默認生成文檔，但沒有我們自定義的說明：
@Api(tags = "用戶管理")
@RestController
public class UserController {
// 注意，對于swagger，不要使用@RequestMapping，
// 因為@RequestMapping支持任意請求方式，swagger會為這個接口生成7種請求方式的接口文檔
@GetMapping("/info")
public String info(String id){
return "aaa";
}
}
我們可以使用@ApiOperation來描述接口，比如：
@ApiOperation(value = "用戶測試",notes = "用戶測試notes")
@GetMapping("/test")
public String test(String id){
return "test";
}
常用配置項：
@Api(tags = "用戶管理")，將接口劃分到了“用戶管理”中，但你可以額外的使用tags = "角色管理"讓角色管理中也有這個接口文檔。定義接口請求參數
上面使用了@ApiOperation來了描述接口，但其實還缺少接口請求參數的說明，下面我們分場景來講。
注意一下，對于GET方式，swagger不推薦使用body方式來傳遞數據，也就是不希望在GET方式時使用json、form-data等方式來傳遞，這時候最好使用路徑參數或者url參數。(😓雖然POSTMAN等是支持的)，所以如果接口傳遞的數據是json或者form-data方式的，還是使用POST方式好。
場景一：請求參數是實體類。
此時我們需要使用@ApiModel來標注實體類，然后在接口中定義入參為實體類即可：
@ApiModel：用來標類
常用配置項：
value：實體類簡稱
description：實體類說明
@ApiModelProperty：用來描述類的字段的意義。
常用配置項：
value：字段說明
example：設置請求示例（Example Value）的默認值，如果不配置，當字段為string的時候，此時請求示例中默認值為"".name：用新的字段名來替代舊的字段名。
allowableValues：限制值得范圍，例如{1,2,3}代表只能取這三個值；[1,5]代表取1到5的值；(1,5)代表1到5的值，不包括1和5；還可以使用infinity或-infinity來無限值，比如[1, infinity]代表最小值為1，最大值無窮大。
required：標記字段是否必填，默認是false,
hidden：用來隱藏字段，默認是false，如果要隱藏需要使用true，因為字段默認都會顯示，就算沒有@ApiModelProperty。
// 先使用@ApiModel來標注類
@ApiModel(value="用戶登錄表單對象",description="用戶登錄表單對象")
public class LoginForm {
// 使用ApiModelProperty來標注字段屬性。
@ApiModelProperty(value = "用戶名",required = true,example = "root")
private String username;
@ApiModelProperty(value = "密碼",required = true,example = "123456")
private String password;
// 此處省略入參賦值時需要的getter,setter,swagger也需要這個
}定義成入參：
@ApiOperation(value = "登錄接口",notes = "登錄接口的說明")
@PostMapping("/login")
public LoginForm login(@RequestBody LoginForm loginForm){
return loginForm;
}效果：
場景二：請求參數是非實體類。
（再說一次：對于GET方式，swagger不推薦使用body方式來傳遞數據，所以雖然Spring MVC可以自動封裝參數，但對于GET請求還是不要使用form-data，json等方式傳遞參數，除非你使用Postman來測試接口，swagger在線測試是不支持這個操作的）
對于非實體類參數，可以使用@ApiImplicitParams和@ApiImplicitParam來聲明請求參數。@ApiImplicitParams用在方法頭上，@ApiImplicitParam定義在@ApiImplicitParams里面，一個@ApiImplicitParam對應一個參數。@ApiImplicitParam常用配置項：
form-data,x-www-form-urlencoded的時候可能不能使用swagger頁面API調試，但可以在后面講到基于BootstrapUI的swagger增強中調試，基于BootstrapUI的swagger支持指定form-data或x-www-form-urlencoded】示例一：聲明入參是URL參數
// 使用URL query參數
@ApiOperation(value = "登錄接口2",notes = "登錄接口的說明2")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",//參數名字
value = "用戶名",//參數的描述
required = true,//是否必須傳入
//paramType定義參數傳遞類型：有path,query,body,form,header
paramType = "query"
)
,
@ApiImplicitParam(name = "password",//參數名字
value = "密碼",//參數的描述
required = true,//是否必須傳入
paramType = "query"
)
})
@PostMapping(value = "/login2")
public LoginForm login2(String username,String password){
System.out.println(username+":"+password);
LoginForm loginForm = new LoginForm();
loginForm.setUsername(username);
loginForm.setPassword(password);
return loginForm;
}示例二：聲明入參是URL路徑參數
// 使用路徑參數
@PostMapping("/login3/{id1}/{id2}")
@ApiOperation(value = "登錄接口3",notes = "登錄接口的說明3")
@ApiImplicitParams({
@ApiImplicitParam(name = "id1",//參數名字
value = "用戶名",//參數的描述
required = true,//是否必須傳入
//paramType定義參數傳遞類型：有path,query,body,form,header
paramType = "path"
)
,
@ApiImplicitParam(name = "id2",//參數名字
value = "密碼",//參數的描述
required = true,//是否必須傳入
paramType = "path"
)
})
public String login3(@PathVariable Integer id1,@PathVariable Integer id2){
return id1+":"+id2;
}示例三：聲明入參是header參數
// 用header傳遞參數
@PostMapping("/login4")
@ApiOperation(value = "登錄接口4",notes = "登錄接口的說明4")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",//參數名字
value = "用戶名",//參數的描述
required = true,//是否必須傳入
//paramType定義參數傳遞類型：有path,query,body,form,header
paramType = "header"
)
,
@ApiImplicitParam(name = "password",//參數名字
value = "密碼",//參數的描述
required = true,//是否必須傳入
paramType = "header"
)
})
public String login4( @RequestHeader String username,
@RequestHeader String password){
return username+":"+password;
}示例四：聲明文件上傳參數
// 有文件上傳時要用@ApiParam，用法基本與@ApiImplicitParam一樣，不過@ApiParam用在參數上
// 或者你也可以不注解，swagger會自動生成說明
@ApiOperation(value = "上傳文件",notes = "上傳文件")
@PostMapping(value = "/upload")
public String upload(@ApiParam(value = "圖片文件", required = true)MultipartFile uploadFile){
String originalFilename = uploadFile.getOriginalFilename();
return originalFilename;
}
// 多個文件上傳時，**swagger只能測試單文件上傳**
@ApiOperation(value = "上傳多個文件",notes = "上傳多個文件")
@PostMapping(value = "/upload2",consumes = "multipart/*", headers = "content-type=multipart/form-data")
public String upload2(@ApiParam(value = "圖片文件", required = true,allowMultiple = true)MultipartFile[] uploadFile){
StringBuffer sb = new StringBuffer();
for (int i = 0; i < uploadFile.length; i++) {
System.out.println(uploadFile[i].getOriginalFilename());
sb.append(uploadFile[i].getOriginalFilename());
sb.append(",");
}
return sb.toString();
}
// 既有文件，又有參數
@ApiOperation(value = "既有文件，又有參數",notes = "既有文件，又有參數")
@PostMapping(value = "/upload3")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",
value = "圖片新名字",
required = true
)
})
public String upload3(@ApiParam(value = "圖片文件", required = true)MultipartFile uploadFile,
String name){
String originalFilename = uploadFile.getOriginalFilename();
return originalFilename+":"+name;
}定義接口響應
定義接口響應，是方便查看接口文檔的人能夠知道接口返回的數據的意義。
響應是實體類：
前面在定義接口請求參數的時候有提到使用@ApiModel來標注類，如果接口返回了這個類，那么這個類上的說明也會作為響應的說明：
// 返回被@ApiModel標注的類對象
@ApiOperation(value = "實體類響應",notes = "返回數據為實體類的接口")
@PostMapping("/role1")
public LoginForm role1(@RequestBody LoginForm loginForm){
return loginForm;
}
響應是非實體類：
swagger無法對非實體類的響應進行詳細說明，只能標注響應碼等信息。是通過@ApiResponses和@ApiResponse來實現的。@ApiResponses和@ApiResponse可以與@ApiModel一起使用。
// 其他類型的,此時不能增加字段注釋，所以其實swagger推薦使用實體類
@ApiOperation(value = "非實體類",notes = "非實體類")
@ApiResponses({
@ApiResponse(code=200,message = "調用成功"),
@ApiResponse(code=401,message = "無權限" )
}
)
@PostMapping("/role2")
public String role2(){
return " {\n" +
" name:\"廣東\",\n" +
" citys:{\n" +
" city:[\"廣州\",\"深圳\",\"珠海\"]\n" +
" }\n" +
" }";
}
Swagger UI增強
你可能會覺得現在這個UI不是很好看，現在有一些第三方提供了一些Swagger UI增強，比較流行的是swagger-bootstrap-ui，我們這里以swagger-bootstrap-ui為例。
UI對比：
使用
1.添加依賴包：
<!--引入swagger--> <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> <!-- 引入swagger-bootstrap-ui依賴包--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.8.7</version> </dependency>
2.在swagger配置類中增加注解@EnableSwaggerBootstrapUI:
@Configuration // 標明是配置類
@EnableSwagger2 //開啟swagger功能
@EnableSwaggerBootstrapUI // 開啟SwaggerBootstrapUI
public class SwaggerConfig {
// 省略配置內容
}3.訪問API：http://localhost:8080/doc.html，即可預覽到基于bootstarp的Swagger UI界面。
優點
1.界面好看了一點
2.上面說過了，基于BootstrapUI的swagger支持指定form-data或x-www-form-urlencoded：
3.支持復制單個API文檔和導出全部API文檔：
整合Spring Security注意
在Spring Boot整合Spring Security和Swagger的時候，需要配置攔截的路徑和放行的路徑，注意是放行以下幾個路徑。
.antMatchers("/swagger**/**").permitAll()
.antMatchers("/webjars/**").permitAll()
.antMatchers("/v2/**").permitAll()
.antMatchers("/doc.html").permitAll() // 如果你用了bootstarp的Swagger UI界面，加一個這個。對于token的處理
在swagger中只支持了簡單的調試，但對于一些接口，我們測試的時候可能需要把token信息寫到header中，目前好像沒看到可以自定義加請求頭的地方？
方法一：
如果你使用了Swagger BootstrapUI，那么你可以在“文檔管理”中增加全局參數，這包括了添加header參數。
方法二：在swagger配置類中增加全局參數配置：
//如果有額外的全局參數，比如說請求頭參數，可以這樣添加
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<Parameter>();
parameterBuilder.name("authorization").description("令牌")
.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
parameters.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2
.apiInfo(apiInfo()) // 用于生成API信息
.select() // select()函數返回一個ApiSelectorBuilder實例,用來控制接口被swagger做成文檔
.apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定掃描哪個包下的接口
.paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔，可以配置這里
.build().globalOperationParameters(parameters);方法三：使用@ApiImplicitParams來額外標注一個請求頭參數，例如：
// 如果需要額外的參數，非本方法用到，但過濾器要用,類似于權限token
@PostMapping("/login6")
@ApiOperation(value = "帶token的接口",notes = "帶token的接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "authorization",//參數名字
value = "授權token",//參數的描述
required = true,//是否必須傳入
paramType = "header"
)
,
@ApiImplicitParam(name = "username",//參數名字
value = "用戶名",//參數的描述
required = true,//是否必須傳入
paramType = "query"
)
})
public String login6(String username){
return username;
}Swagger的安全管理
1.如果你整合了權限管理，可以給swagger加上權限管理，要求訪問swagger頁面輸入用戶名和密碼，這些是spring security和shiro的事了，這里不講。
2.如果你僅僅是不想在正式環境中可以訪問，可以在正式環境中關閉Swagger自動配置，這就不會有swagger頁面了。使用@Profile({"dev","test"})注解來限制只在dev或者test下啟用Swagger自動配置。
然后在Spring Boot配置文件中修改當前profilespring.profiles.active=release，重啟之后，此時無法訪問http://localhost:8080/swagger-ui.html
看完這篇關于Spring Boot如何整合swagger的文章，如果覺得文章內容寫得不錯的話，可以把它分享出去給更多人看到。
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
