如何讓介面文件自動生成，SpringBoot中Swagger的使用
阿新 • • 發佈：2019-06-20
目錄
- 一、在SpringBoot專案中配置Swagger2
- 1、pom.xml中對Swagger2的依賴
- 2、編寫配置類啟用Swagger
- 3、配置實體類的文件
- 4、配置介面的文件
- 5、訪問文件
- 二、介面前後臺分離的配置
- 1、介面分離
- 2、對前後臺介面進行分組配置
在開發過程中，java後端需要與客戶端進行互動，需要將後端的介面及引數寫成文件給呼叫者查閱。一個問題也有此而生，需求改動頻繁，介面設計也會隨之改動，文件修改的不及時會帶來很大的問題。
Swagger是一個自動生成文件的工具，可以線上查閱文件，減少了開發人員的負擔，下面我們就來看看如何在SpringBoot中使用Swagger。
一、在SpringBoot專案中配置Swagger2
1、pom.xml中對Swagger2的依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
2、編寫配置類啟用Swagger
Swagger2Config.java
@Configuration //配置類 @EnableSwagger2 //啟用Swagger2 public class Swagger2Config { @Bean public Docket apiConfig() { return new Docket(DocumentationType.SWAGGER_2)//建立Swagger2型別的文件 .apiInfo(apiInfo());//apiInfo方法返回配置的介面資訊 } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("使用者中心微服務前臺網站API")//介面標題 .description("此文件描述了使用者中心前臺網站的基本API介面")//介面描述 .version("1.0")//介面版本 .contact(new Contact("Jack", "http://www.jikedaquan.com", "[email protected]"))//聯絡方式：名字、網址、郵箱 .build(); } }
3、配置實體類的文件
實體類Member
//對實體名生成文件描述
@ApiModel(value="Member物件")
public class Member{
//對屬性生成文件描述
@ApiModelProperty(value = "學員ID")
private Long memberId;
//required 將屬性描述標記為必須
@ApiModelProperty(value = "手機號",required = true)
private String mobile;
@ApiModelProperty(value = "郵箱",required = true)
private String email;
@ApiModelProperty(value = "密碼",required = true)
private String password;
@ApiModelProperty(value = "使用者名稱")
private String userName;
//將不希望在文件中看到的屬性使用hidden隱藏
@ApiModelProperty(value = "邏輯刪除 1已刪除 0未刪除",hidden = true)
private Boolean deleted;
//省略其他欄位
}4、配置介面的文件
控制器介面類
@RestController
//生成api介面的文件描述
@Api(description = "學員管理")
@RequestMapping("/ucenter/member")
public class MemberController {
@Autowired
private MemberService memberService;
//定義請求方法的名字和詳細描述
@ApiOperation(value = "註冊學員", notes = "updateTime,createTime無需新增，這是前臺系統使用者的註冊功能，前提是使用者已經接收了驗證碼")
@PostMapping
public boolean register(
//定義請求引數的文件描述 name的值是要描述的引數的名字
@ApiParam(name = "member", value = "學員物件", required = true)
@RequestBody Member member) {
boolean result = memberService.save(member);
return result;
}
//省略其他
}5、訪問文件
文件地址：localhost:8080/swagger-ui.html
二、介面前後臺分離的配置
為什麼要對介面進行前後臺分離？因為前臺和後臺的功能有些相同，但有些差異，例如後臺管理員可以刪除使用者，但前臺是沒有刪除使用者的功能的，將介面和文件分離更有利於管理維護。
1、介面分離
前臺介面
@RestController
@Api(description = "前端學員管理")
@RequestMapping("/api/ucenter/member")
public class MemberController {
@Autowired
private MemberService memberService;
@ApiOperation(value = "註冊學員", notes = "updateTime,createTime無需新增，這是前臺系統使用者的註冊功能，前提是使用者已經接收了驗證碼")
@PostMapping
public boolean register(
@ApiParam(name = "member", value = "學員物件", required = true)
@RequestBody Member member) {
boolean result = memberService.save(member);
return result;
}
}後臺介面放在同級下的admin包中
@RestController
@Api(description = "學員管理")
@RequestMapping("/admin/ucenter/member")
public class AdminMemberController {
@Autowired
private MemberService memberService;
@ApiOperation(value = "返回所有學員列表")
@GetMapping
public List<Member> list() {
return memberService.list(null);
}
@ApiOperation(value = "根據id刪除學員")
@DeleteMapping(value = "{memberId}")
public boolean deleteById(@ApiParam(name = "memberId", value = "學員id", required = true)
@PathVariable Long memberId) {
boolean result = memberService.removeById(memberId);
return result;
}
@ApiOperation(value = "註冊學員", notes = "updateTime,createTime無需新增，這是前臺系統使用者的註冊功能，前提是使用者已經接收了驗證碼")
@PostMapping
public boolean register(
@ApiParam(name = "member", value = "學員物件", required = true)
@RequestBody Member member) {
boolean result = memberService.save(member);
return result;
}
}這樣就有了同一個實體的不同的介面
2、對前後臺介面進行分組配置
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
//前臺api介面文件
public Docket webApiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")//組名
.apiInfo(webApiInfo())
.select()//建立ApiSelectorBuilder物件
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))//過濾掉 admin 介面
.paths(Predicates.not(PathSelectors.regex("/error.*")))//過濾掉 error 介面
.build();
}
@Bean
//後臺管理員api文件
public Docket adminApiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("adminApi")
.apiInfo(adminApiInfo())
.select()//建立ApiSelectorBuilder物件
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))//只顯示 admin 介面
.build();
}
private ApiInfo webApiInfo() {
return new ApiInfoBuilder()
.title("使用者中心微服務前臺網站API")
.description("此文件描述了使用者中心前臺網站的基本API介面")
.version("1.0")
.contact(new Contact("Jack", "http://www.jikedaquan.com", "[email protected]"))
.build();
}
private ApiInfo adminApiInfo() {
return new ApiInfoBuilder()
.title("使用者中心微服務後臺管理系統的API")
.description("此文件描述了使用者中心後臺管理系統的基本API介面")
.version("1.0")
.contact(new Contact("Jack", "http://www.jikedaquan.com", "[email protected]"))
.build();
}
}