嚐鮮剛釋出的 SpringFox 3.0.0，以前造的輪子可以不用了...
最近 SpringFox 3.0.0 釋出了，距離上一次大版本2.9.2足足有2年多時間了。可能看到這個名字，很多讀者會有點陌生。但是，只要給大家看一下這兩個依賴，你就知道了！
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
<scope>compile</scope>
</dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
<scope>compile</scope>
</dependency>
當我們在使用Spring MVC寫介面的時候，為了生成API檔案，為了方便整合Swagger，都是用這個SpringFox的這套封裝。但是，自從2.9.2版本更新之後，就一直沒有什麼動靜，也沒有更上Spring Boot的大潮流，有一段時間還一直都是寫個配置類來為專案新增檔案配置的。為此，之前就造了這麼個輪子：
也沒什麼難度，就是造的早，所以得到了不少Star。現在SpringFox出了一個starter，看了一下功能，雖然還不完美，但相較於之前我們自己的輪子來說還是好蠻多的。來看看這個版本有些什麼亮點：
- Spring 5，Webflux 支援（僅請求對映支援，尚不支援功能端點）
- Spring Integration 支援
- Spring Boot 支援 springfox-boot-starter 依賴性（零配置，自動配置支援）
- 具有自動完成功能的檔案化配置屬性
- 更好的規範相容性
- 支援 OpenApi 3.0.3
- 幾乎零依賴性（唯一需要的庫是 spring-plugin、pswagger-core）
- 現有的 swagger2 註釋將繼續有效，並豐富 open API 3.0 規範
對於這次的更新，我覺得比較突出的幾點：Webflux的支援，目前的輪子就沒有做到；對OpenApi 3的支援；以及對Swagger 2的相容（可以比較方便的做升級了）。
上手嚐鮮
說那麼多，不如來一發程式實驗下更直接！
第一步：建立一個Spring Boot專案，這裡不展開，不會的看以前的教程：快速入門
第二步：pom.xml中新增依賴：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
<dependency>
現在簡潔了不少，一個依賴搞定！
第三步：應用主類增加註解@EnableOpenApi。
@EnableOpenApi
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
第四步：配置一些介面例子，比如：
@Api(tags="使用者管理")
@RestController
public class UserController {
@ApiOperation("建立使用者")
@PostMapping("/users")
public User create(@RequestBody @Valid User user) {
return user;
}
@ApiOperation("使用者詳情")
@GetMapping("/users/{id}")
public User findById(@PathVariable Long id) {
return new User("bbb", 21, "上海", "[email protected]");
}
@ApiOperation("使用者列表")
@GetMapping("/users")
public List<User> list(@ApiParam("檢視第幾頁") @RequestParam int pageIndex,
@ApiParam("每頁多少條") @RequestParam int pageSize) {
List<User> result = new ArrayList<>();
result.add(new User("aaa", 50, "北京", "[email protected]"));
result.add(new User("bbb", 21, "廣州", "[email protected]"));
return result;
}
@ApiIgnore
@DeleteMapping("/users/{id}")
public String deleteById(@PathVariable Long id) {
return "delete user : " + id;
}
}
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("使用者基本資訊")
public class User {
@ApiModelProperty("姓名")
@Size(max = 20)
private String name;
@ApiModelProperty("年齡")
@Max(150)
@Min(1)
private Integer age;
@NotNull
private String address;
@Pattern(regexp = "^[a-zA-Z0-9_-][email protected][a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
private String email;
}
第五步：啟動應用！訪問swagger頁面：http://localhost:8080/swagger-ui/index.html
注意：
- 這次更新，移除了原來預設的swagger頁面路徑：
http://host/context-path/swagger-ui.html，新增了兩個可訪問路徑：http://host/context-path/swagger-ui/index.html和http://host/context-path/swagger-ui/- 通過調整日誌級別，還可以看到新版本的swagger檔案介面也有新增，除了以前老版本的檔案介面
/v2/api-docs之外，還多了一個新版本的/v3/api-docs介面。
本系列教程《Spring Boot 2.x基礎教程》點選直達！
程式碼示例
本文的相關例子可以檢視下面倉庫中的chapter2-7目錄：
- Github：https://github.com/dyc87112/SpringBoot-Learning/
- Gitee：https://gitee.com/didispace/SpringBoot-Learning/
如果您覺得本文不錯，歡迎Star支援，您的關注是我堅持的動力！
本文首發：嚐鮮剛釋出的 SpringFox 3.0.0，以前造的輪子可以不用了...，轉載請註明出處。
歡迎關注我的公眾號：程式猿DD，獲得獨家整理的學習資源和日常乾貨推送。點選直達本系列教程目錄。