1. 引入依賴
<!--依賴管理 --> <dependencies> <dependency> <!--添加Web依賴 --> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency><!--添加Swagger依賴 --> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency><!--添加Swagger-UI依賴 --> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency> <dependency> <!--添加熱部署依賴 --> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> </dependency> <dependency><!--添加Test依賴 --> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies>
2. 添加配置
@Configuration //標記配置類 @EnableSwagger2 //開啟在線接口文檔 public class Swagger2Config { /** * 添加摘要信息(Docket) */ @Bean public Docket controllerApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("標題:某公司_用戶信息管理系統_接口文檔") .description("描述:用於管理集團旗下公司的人員信息,具體包括XXX,XXX模塊...") .contact(new Contact("一只襪子", null, null)) .version("版本號:1.0") .build()) .select() .apis(RequestHandlerSelectors.basePackage("com.hehe.controller")) .paths(PathSelectors.any()) .build(); } }
3. 編寫接口文檔
Swagger2 基本使用:
- @Api 描述類/接口的主要用途
- @ApiOperation 描述方法用途
- @ApiImplicitParam 描述方法的參數
- @ApiImplicitParams 描述方法的參數(Multi-Params)
- @ApiIgnore 忽略某類/方法/參數的文檔
Swagger2 使用注解來編寫文檔:
Swagger2編寫接口文檔相當簡單,只需要在控制層(Controller)添加注解來描述接口信息即可。例如:
package com.hehe.controller; @Api("用戶信息管理") @RestController @RequestMapping("/user/*") public class UserController { private final static List<User> userList = new ArrayList<>(); { userList.add(new User("1", "admin", "123456")); userList.add(new User("2", "jacks", "111111")); } @ApiOperation("獲取列表") @GetMapping("list") public List userList() { return userList; } @ApiOperation("新增用戶") @PostMapping("save") public boolean save(User user) { return userList.add(user); } @ApiOperation("更新用戶") @ApiImplicitParam(name = "user", value = "單個用戶信息", dataType = "User") @PutMapping("update") public boolean update(User user) { return userList.remove(user) && userList.add(user); } @ApiOperation("批量刪除") @ApiImplicitParam(name = "users", value = "N個用戶信息", dataType = "List<User>") @DeleteMapping("delete") public boolean delete(@RequestBody List<User> users) { return userList.removeAll(users); } } package com.hehe.entity; public class User { private String userId; private String username; private String password; public User() { } public User(String userId, String username, String password) { this.userId = userId; this.username = username; this.password = password; } @Override public boolean equals(Object o) { if (this == o) { return true; } if (o == null || getClass() != o.getClass()) { return false; } User user = (User) o; return userId != null ? userId.equals(user.userId) : user.userId == null; } @Override public int hashCode() { int result = userId != null ? userId.hashCode() : 0; result = 31 * result + (username != null ? username.hashCode() : 0); result = 31 * result + (password != null ? password.hashCode() : 0); return result; } public String getUserId() { return userId; } public void setUserId(String userId) { this.userId = userId; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } }
4. 查閱接口文檔
編寫文檔完成之后,啟動當前項目,在瀏覽器打開:
[ http://localhost:8080/swagger-ui.html ]