轻轻松松实现Swagger2和SpringBoot的整合

一、Swagger2介绍    

前后端分离开发模式中，api文档是最好的沟通方式。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

及时性 ：接口变更后，能够及时准确地通知相关前后端开发人员。

规范性 ：并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息。

一致性 ：接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧。

可测性 ：直接在接口文档上进行测试，以方便理解业务。

接下来，我们通过一个小案例来了解如何整合Swagger2和SpringBoot。

二、配置Swagger2    

1.创建SpringBoot项目swagger-test

2.在项目的pom文件中引入相关依赖

<parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>2.2.1.RELEASE</version>

<relativePath/> <!-- lookup parent from repository -->

</parent>

<groupId>com.atguigu</groupId>

<artifactId>swagger-test</artifactId>

<version>1.0-SNAPSHOT</version>

<dependencies>

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<!--swagger-->

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

</dependencies>

3.在项目的pom文件中引入相关依赖​​​​​​​

public class User {

private String name;

private Integer age;

private String addr;

}

4.在项目中，创建controller类​​​​​​​

@RestController

@RequestMapping("/admin")

public class DemoController {

@GetMapping("getUser")

public User getUser(User u){

User user = new User();

user.setName("张三");

user.setAge(18);

user.setAddr("北京市昌平区宏福苑");

return user;

}

}

5.在项目中，创建Swagger的配置类

   创建包com.atguigu.config，在包里创建配置类Swagger2Config。​​​​​​​

@Configuration

@EnableSwagger2

public class Swagger2Config {

@Bean

public Docket webApiConfig() {

return new Docket(DocumentationType.SWAGGER_2);

}

}

6.通过地址访问测试

三、Swagger2常用配置和注解    

1.对文档的整体添加页面标题、描述信息、创建人等信息​​​​​​​

@Configuration

@EnableSwagger2

public class Swagger2Config {

@Bean

public Docket adminApiConfig(){

return new Docket(DocumentationType.SWAGGER_2)

.groupName("adminApi")

.apiInfo(adminApiInfo())

.select()

//只显示admin路径下的页面

.paths(Predicates.and(PathSelectors.regex("/admin/.*")))

.build();

}

private ApiInfo adminApiInfo(){

return new ApiInfoBuilder()

//页面标题

.title("后台管理系统-API文档")

//描述信息

.description("本文档描述了后台管理系统微服务接口定义")

//版本号

.version("1.0")

//创建人

.contact(new Contact("atguigu", "http://atguigu.com", "XXXXX@qq.com"))

.build();

}

}

使用后效果如下：

2.控制层常用的注解

   @Api  使用位置在类上，描述介绍整个类

   @ApiOperation 使用位置在方法上，用来介绍方法

   @ApiParam 使用位置在参数上，用来介绍参数

使用后的效果如下：

3.在modle类上常用的注解

   @ApiModel使用位置在modle类上，用来介绍实体类

   @ApiModelProperty  使用位置在modle类的属性上，用来介绍解释属性

使用后的效果如下：

四、总结    

通过以上的配置，我们可以轻松的实现了SpringBoot与Swagger2的整合，这样就可以使客户端和文件系统作为服务器以同样的速度来更新，提高了开发效率。