源碼地址：https://github.com/laolunsi/spring-boot-examples

目前SpringBoot常被用于開(kāi)發(fā)Java Web應(yīng)用，特別是前后端分離項(xiàng)目。為方便前后端開(kāi)發(fā)人員進(jìn)行溝通，我們?cè)赟pringBoot引入了Swagger。

Swagger作用于接口，讓接口數(shù)據(jù)可視化，尤其適用于Restful APi

本節(jié)分兩部分介紹，第一部分是SpringBoot引入Swagger的兩種方式，第二部分是詳細(xì)介紹在Web接口上應(yīng)用Swagger的注解。

本篇文章使用SpringBoot 2.1.10.RELEASE和springfox-swagger 2.9.2

一、SpringBoot引入Swagger的兩種方式

目前SpringBoot有兩種使用Swagger的方式：

引入swagger原生依賴(lài)springfox-swagger2和springfox-swagger2-ui

引入國(guó)內(nèi)Spring4All社區(qū)開(kāi)發(fā)的依賴(lài)swagger-spring-boot-starter

Spring4All出品的依賴(lài)采取配置文件的方式進(jìn)行配置，而原生依賴(lài)是通過(guò)java config類(lèi)來(lái)設(shè)置的。

1.1 原生配置Swagger

maven依賴(lài)：

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version></dependency>

swagger配置類(lèi)：

/** * swagger2配置類(lèi) */@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage('com.example')) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title('基于Swagger構(gòu)建的Rest API文檔') .description('更多請(qǐng)咨詢(xún)服務(wù)開(kāi)發(fā)者eknown') .contact(new Contact('空夜', 'http://www.eknown.cn', 'eknown@163.com')) .termsOfServiceUrl('http://www.eknown.com') .version('1.0') .build(); }}

從這里可以看出Swagger的一個(gè)缺點(diǎn)：無(wú)法通過(guò)SpringBoot的配置文件進(jìn)行配置，所以配置并不能靈活轉(zhuǎn)變。

spring4all社區(qū)出品的swagger-spring-boot-starter可以解決這個(gè)問(wèn)題。

1.2 基于spring4all配置swagger

Spring4All社區(qū)的博主程序猿DD和小火兩個(gè)人開(kāi)發(fā)了Spring Boot Starter Swagger，目前已經(jīng)在maven官方倉(cāng)庫(kù)上線(xiàn)了。

選擇第一個(gè)，引入該依賴(lài)：

<dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.9.0.RELEASE</version></dependency>

這種方式的Swagger配置是通過(guò)application配置文件進(jìn)行的。下面給出一個(gè)示例：

server: port: 8106swagger: base-path: /** base-package: ’com.example’ title: ’spring-boot-swagger-demo’ description: ’基于Swagger構(gòu)建的SpringBoot RESTApi 文檔’ version: ’1.0’ contact: name: ’空夜’ url: ’http://www.eknown.cn’ email: ’eknown@163.com’

二、應(yīng)用Swagger構(gòu)建接口可視化

2.1 Controller類(lèi)添加Swagger注解

下面給一個(gè)簡(jiǎn)單的示例：

@Api(tags = '用戶(hù)管理')@RestController@RequestMapping(value = 'user')public class UserController { // 模擬數(shù)據(jù)庫(kù)存儲(chǔ)的用戶(hù) private static Map<Integer, User> userMap; static { userMap = new ConcurrentHashMap<>(); User user = new User(0, 'admin', true, new Date()); userMap.put(user.getId(), user); } @ApiOperation('列表查詢(xún)') @GetMapping(value = '') public List<User> list() { return new ArrayList<>(userMap.values()); } @ApiOperation(value = '獲取用戶(hù)詳細(xì)信息', notes = '路徑參數(shù)ID') @GetMapping(value = '{id}') public User detail(@PathVariable Integer id) { return userMap.get(id); } @ApiOperation(value = '新增或更新用戶(hù)信息', notes = 'insert和update共用' , response = User.class) @PostMapping(value = '') public User add(@RequestBody User user) { if (user == null || user.getId() == null || !StringUtils.isEmpty(user.getName()) || userMap.containsKey(user.getId())) { return null; } user.setUpdateTime(new Date()); userMap.put(user.getId(), user); return user; } @ApiOperation(value = '刪除用戶(hù)') @DeleteMapping(value = '{id}') public Boolean delete(@ApiParam(name = '用戶(hù)ID', required = true, example = '100') @PathVariable Integer id) { if (userMap.containsKey(id)) { userMap.remove(id); return true; } return false; }}

2.2 參數(shù)實(shí)體類(lèi)添加Swagger注解

實(shí)體類(lèi)也需要添加一些注解，以便前端開(kāi)發(fā)人員確定參數(shù)的意義、類(lèi)型、示例等。

@ApiModel(description = '用戶(hù)類(lèi)')public class User { @ApiModelProperty(value = 'ID', example = '100') private Integer id; @ApiModelProperty(value = '姓名', example = 'laolunsi') private String name; @ApiModelProperty(value = '是否啟用', example = '1') private Boolean enable; @ApiModelProperty('更新時(shí)間') private Date updateTime; public User(Integer id, String name, Boolean enable, Date updateTime) { this.id = id; this.name = name; this.enable = enable; this.updateTime = updateTime; } // ... ignore getter and setter methods}

2.3 測(cè)試

啟動(dòng)項(xiàng)目，訪(fǎng)問(wèn)http://localhost:port/swagger-ui.html

如果存在server.servlet.context-path配置，那么訪(fǎng)問(wèn)地址是http://localhost:port/context-path/swagger-ui.html

這樣，接口就一目了然了，swagger還支持在線(xiàn)測(cè)試接口，與postman的作用類(lèi)似。

好，到目前為止，我們已經(jīng)成功在SpringBoot項(xiàng)目中整合了Swagger，這樣前后端開(kāi)發(fā)對(duì)接就有了標(biāo)準(zhǔn)！

以上就是Spring Boot 使用 Swagger 構(gòu)建 RestAPI 接口文檔的詳細(xì)內(nèi)容，更多關(guān)于Spring Boot 整合 Swagger的資料請(qǐng)關(guān)注好吧啦網(wǎng)其它相關(guān)文章！