Spring Boot 2.x基礎教程:使用SpringFox 3生成Swagger文檔
最近 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, "上海", "[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_-]+@[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
支持,您的關注是我堅持的動力!