Spring Boot 使用 Swagger 构建 RestAPI 接口文档

Spring Boot 使用 Swagger 构建 RestAPI 接口文档

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

目前SpringBoot常被用于开发java Web应用，特别是前后端分离项目。为方便前后端开发人员进行沟通，我们在SpringBoot引入了Swagger。

Swagger作用于接口，让接口数据可视化，尤其适用于Restful APi

本节分两部分介绍，第一部分是SpringBoot引入Swagger的两种方式，第二部分是详细介绍在Web接口上应用Swagger的注解。

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

一、SpringBoot引入Swagger的两种方式

目前SpringBoot有两种使用Swagger的方式：

引入swagger原生依赖springfox-swagger2和springfox-swagger2-ui

引入国内Spring4All社区开发的依赖swagger-spring-boot-starter

Spring4All出品的依赖采取配置文件的方式进行配置，而原生依赖是通过java config类来设置的。

1.1 原生配置Swagger

maven依赖：

io.springfox

springfox-swagger2

2.9.2

io.springfox

springfox-swagger-ui

2.9.2

swagger配置类：

/**

* swagger2配置类

*/

@Configuration

@EnavbaItfTbleSwagger2

public 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构建的Rest API文档")

.description("更多请咨询服务开发者eknown")

.contact(new Contact("空夜", "http://eknown.cn", "eknown@163.com"))

.termsOfShttp://erviceUrl("http://eknown.com")

.version("1.0")

.build();

}

}

从这里可以看出Swagger的一个缺点：无法通过SpringBoot的配置文件进行配置，所以配置并不能灵活转变。

spring4all社区出品的swagger-spring-boot-starter可以解决这个问题。

1.2 基于spring4all配置swagger

Spring4All社区的博主程序猿DD和小火两个人开发了Spring Boot Starter Swagger，目前已经在maven官方仓库上线了。

选择第一个，引入该依赖：

com.spring4all

swagger-spring-boot-starter

1.9.0.RELEASE

这种方式的Swagger配置是通过application配置文件进行的。下面给出一个示例：

server:

port: 8106

swagger:

base-path: /**

base-package: 'com.example'

title: 'spring-boot-swagger-demo'

description: '基于Swagger构建的SpringBoot RESTApi 文档'

version: '1.0'

contact:

name: '空夜'

url: 'http://eknown.cn'

email: 'eknown@163.com'

二、应用Swagger构建接口可视化

2.1 Controller类添加Swagger注解

下面给一个简单的示例：

@Api(tags = "用户管理")

@RestController

@RequestMapping(value = "user")

public class UserController {

// 模拟数据库存储的用户

private static Map userMap;

static {

userMap = new ConcurrentHashMap<>();

User user = new User(0, "admin", true, new Date());

userMap.put(user.getId(), user);

}

@ApiOperation("列表查询")

@GetMapping(value = "")

public List list() {

return new ArrayList<>(userMap.values());

}

@ApiOperation(value = "获取用户详细信息", notes = "路径参数ID")

@GetMapping(value = "{id}")

public User detail(@PathVariable Integer id) {

return userMap.get(id);

}

@ApiOperation(value = "新增或更新用户信息", 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 = "删除用户")

@DeleteMapping(value = "{id}")

public Boolean delete(@ApiParam(name = "用户ID", required = true, example = "100") @PathVariable Integer id) {

if (userMap.containsKey(id)) {

userMap.remove(id);

return true;

}

return false;

}

}

2.2 参数实体类添加Swagger注解

实体类也需要添加一些注解，以便前端开发人员确定参数的意义、类型、示例等。

@ApiModel(description = "用户类")

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("更新时间")

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 测试

启动项目，访问http://localhost:port/swagger-ui.html

如果存在server.servlet.context-path配置，那么访问地址是http://localhost:port/context-path/swagger-ui.html

这样，接口就一目了然了，swagger还支持在线测试接口，与postman的作用类似。

好，到目前为止，我们已经成功在SpringBoot项目中整合了Swagger，这样前后端开发对接就有了标准！

以上就是Spring Boot 使用 Swagger 构建 RestAPI 接口文档的详细内容，更多关于Spring Boot 整合 Swagger的资料请关注我们其它相关文章！

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。