嚐鮮剛釋出的 SpringFox 3.0.0,以前造的輪子可以不用了...

程式猿DD發表於2020-07-18

最近 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>
<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, "上海", "aaa@bbb.com");
    }

    @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, "北京", "aaa@ccc.com"));
        result.add(new User("bbb", 21, "廣州", "aaa@ddd.com"));
        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_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
    private String email;

}

第五步:啟動應用!訪問swagger頁面:http://localhost:8080/swagger-ui/index.html

注意:

  1. 這次更新,移除了原來預設的swagger頁面路徑:http://host/context-path/swagger-ui.html,新增了兩個可訪問路徑:http://host/context-path/swagger-ui/index.htmlhttp://host/context-path/swagger-ui/
  2. 通過調整日誌級別,還可以看到新版本的swagger文件介面也有新增,除了以前老版本的文件介面/v2/api-docs之外,還多了一個新版本的/v3/api-docs介面。

本系列教程《Spring Boot 2.x基礎教程》點選直達!

程式碼示例

本文的相關例子可以檢視下面倉庫中的chapter2-7目錄:

如果您覺得本文不錯,歡迎Star支援,您的關注是我堅持的動力!

本文首發:嚐鮮剛釋出的 SpringFox 3.0.0,以前造的輪子可以不用了...,轉載請註明出處。
歡迎關注我的公眾號:程式猿DD,獲得獨家整理的學習資源和日常乾貨推送。點選直達本系列教程目錄

相關文章