07 Spring Boot整合 Swagger2

1. swagger简介

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础， 对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。 文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

2. Swagger2和swagger的区别

springfox 的官方给出了介绍：

总结下来就是：

1. Swagger

   是一种规范。

2. springfox-swagger

   是基于 Spring 生态系统的该规范的实现。

3. springfox-swagger-ui

   是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。

3. Spring Boot整合 Swagger2

步骤1：引入Swagger2的依赖，帮助我们自动生成这个json文件。

<!-- 引入Swagger2的依赖，帮助我们自动生成这个json文件 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>

步骤2：编写Swagger2的配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.cui.springboot01"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful API")
.description("rest api文档构建利器")
//.termsOfServiceUrl()
.contact(new Contact("cuiyonghua","","320479069@qq.com"))
.version("1.0")
.build();
}
}

步骤3：编写接口

@Controller
public class HelloController {
@ResponseBody
@RequestMapping("/hello")
public String hello(){
return "Hello World!！！";
}
}

步骤4：测试
基本配置已经能满足一个生成API文档的基本要求了，启动项目，访问:http://localhost/swagger-ui.html 会看到如下界面:

至此，Spring Boot整合 Swagger2 完毕。

步骤4：Swagger2 注解的使用

• @Api

  : 描述类/接口的主要用途；

• @ApiOperation

  : 描述方法用途；

• @ApiImplicitParam

  : 描述方法的参数；

• @ApiImplicitParams

  : 描述方法的参数(Multi-Params)；

• @ApiParam

  :请求属性；

• @ApiIgnore

  : 忽略某类/方法/参数的文档

• @ApiResponse

  ：响应配置

• @ApiResponses

  ：响应集配置

• @ResponseHeader

  : 响应头设置

• @ApiModelProperty

  :添加和操作模型属性的数据

1.在上面代码的基础上，新建一个User实体

public class User {
@ApiModelProperty(hidden = true)
private String id;
@ApiModelProperty(value = "用户名")
private String username;

@ApiModelProperty(hidden = true,value = "密码")//忽略了 password 字段
private String password;
@ApiModelProperty(value = "邮箱")
private String email;

private Integer age;

private Boolean enabled;

//省略get/set,和构造方法

2.在Controller中添加如下接口

@RestController
@RequestMapping(value = "/user")
@Api(description = "用户管理")
public class UserController {

ArrayList<User> users = new ArrayList<>();

@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
@RequestMapping(value = {""}, method = RequestMethod.GET)
public List<User> hello() {
users.add(new User("张三丰"));
users.add(new User("张无忌"));
return users;
}

@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@RequestMapping(value = "/create", method = RequestMethod.POST)
public User postUser(User user) {
return user;
}

@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
@RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
public User getUser(@ApiParam(value = "用户id", required = true)
@PathVariable(value = "id") String id) {
return new User(id, "cyh", "123456");
}
}

3.启动服务，测试