一、是什麼?
swagger,俗稱絲襪哥,是用來生成接口文檔的。沒有使用swagger的時候,你寫完後端接口,得自己將後端接口地址一個個地整理出來,告訴別人這個接口是幹嘛的,要傳哪些參數,正常情況下返回的參數是咋樣的,非正常情況返回的又是咋樣的。很麻煩有木有?有了絲襪哥,你只需要簡單地加上幾個註解,然後會有一個絲襪哥的ui界面,裏面就包含了接口的所有信息,灰常地方便。
二、 怎麼用?
以下操作基於springboot項目。
1. 添加依賴:
<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相關注解:
@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
3. 配置swagger:
新建一個配置類,對swagger進行配置:
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.zhu.demo.swagger")) // 這個包下的會被swagger掃描到
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
.title("SpringBoot整合Swagger") // swagger-ui展示的標題
.description("這是一個測試springboot整合swagger的項目") // swagger-ui頁面的描述
.version("1.0") // api版本
.contact(new Contact("聯繫我","www.baidu.com","[email protected]")) // 聯繫方式
.license("lisence_description") // license
.licenseUrl("http://www.baidu.com") // license地址
.build());
}
}
這個配置類對swagger做了一些基礎的配置,最重要的就是掃描路徑,即basePackage,其他都是頁面上展示的東西。配置完這個,然後啓動,訪問:localhost:端口/swagger-ui.html
,就可以看到如下頁面:
4. 接口中使用swagger:
假如我現在在swagger能掃描到的包下新建如下幾個類:
@Data
public class User {
private long userId;
private String userName;
private String userPassword;
private int userAge;
}
@RestController
@RequestMapping("/user")
public class UserController {
@GetMapping("/{userId}")
public String query(@PathVariable("userId") Long userId){
User user = new User();
user.setUserId(userId);
user.setUserName("testName");
user.setUserPassword("testPassword");
user.setUserAge(18);
return JSONObject.toJSONString(user);
}
@PostMapping("/addUser")
public String add(User user){
JSONObject jsonObject = new JSONObject();
jsonObject.put("status", "0");
jsonObject.put("message", "success");
jsonObject.put("user", user);
return jsonObject.toJSONString();
}
}
你重啓項目,再次訪問swagger-ui,你會發現,頁面中就已經有這兩個接口了,如下:
點擊try it out,就可以對接口進行測試了。但是,這樣看起來怪怪的,因爲沒有接口的說明,也沒有字段的說明,字段是否能爲空也沒有限制,響應示例也沒有。
5. 加controller的說明:
在UserController類上加上註解:
@Api(tags = "用戶模塊")
public class UserController {
……
}
加上這個之後,界面就變成這樣了:
6. 其他註解:
@ApiOperation("獲取用戶信息")
:加在方法上,表示該接口是幹嘛的,括號裏面的是該方法的說明;@ApiParam(name="userId",value="用戶id",required=true, defaultValue = "1")
:加在方法參數上,說明該參數是什麼意思,是否必須,還可以設置一個默認值;
如果參數是對象,那麼怎麼搞?比如上面的add方法,參數是User對象,那麼就在user類上用如下註解:
@ApiModel(value="User",description="用戶對象")
:加在User類上,說明這個對象是幹啥的@ApiModelProperty(value="用戶名",name="userName",example="律政先鋒")
:加在user類屬性上,說明這個字段是幹啥的
這樣,在接口中就會顯示這些參數的釋義了。
7. 顯示model:
我們還可以直接將整個User類暴露在接口文檔中,只需要在add方法中,加上@RequestBody
,那麼在頁面中就會顯示model了。
加上配置後的代碼如下:
@RestController
@RequestMapping("/user")
@Api(tags = "用戶模塊")
public class UserController {
@ApiOperation("獲取用戶信息") // 接口描述
@GetMapping("/{userId}")
public String query(@ApiParam(name="userId",value="用戶id",required=true) @PathVariable("userId") Long userId){
User user = new User();
user.setUserId(userId);
user.setUserName("testName");
user.setUserPassword("testPassword");
user.setUserAge(18);
return JSONObject.toJSONString(user);
}
@ApiOperation("新增用戶信息") // 接口描述
@PostMapping("/addUser")
public String add(@RequestBody User user){
JSONObject jsonObject = new JSONObject();
jsonObject.put("status", "0");
jsonObject.put("message", "success");
jsonObject.put("user", user);
return jsonObject.toJSONString();
}
}
@Data
@ApiModel(value="User",description="用戶對象")
public class User {
@ApiModelProperty(value="用戶id",name="userId",example="123")
private long userId;
@ApiModelProperty(value="用戶名",name="userName",example="律政先鋒")
private String userName;
@ApiModelProperty(value="用戶密碼",name="userPassword",example="lvzf")
private String userPassword;
@ApiModelProperty(value="用戶年齡",name="userAge",example="18")
private int userAge;
}
最終效果如下: