SpringBoot-Swagger集成

最新推荐文章于 2023-04-19 17:45:40 发布

六道佩奇。

最新推荐文章于 2023-04-19 17:45:40 发布

阅读量122

点赞数

分类专栏： SpringBoot

本文链接：https://blog.csdn.net/weixin_44900198/article/details/106114272

版权

SpringBoot 专栏收录该内容

11 篇文章 0 订阅

订阅专栏

初识Swagger

Swagger官网:https://swagger.io/

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

1. 环境搭建

创建SpringBoot-web项目

1. 导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3. 编写HelloWorld

为了保证可以成功运行

4. 配置Swagger配置类

@Configuration  // 表明是一个Spring配置类
@EnableSwagger2 // 开启Swagger2的自动配置
public class SwaggerConfig {

}

5. 测试

访问Swagger API 文档

路径：

http://localhost:8080/swagger-ui.html
在这里插入图片描述

配置Swagger

编写Swagger配置类

因为 Swagger 的 bean 实例是 Docket，所以我们通过配置Docket实例，并将其加入到Spring容器中来实现对Swagger的配置

SwaggerConfig.java

@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

   // 配置Swagger的Docket实例
   @Bean
   public Docket docket(){

       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo()); // 关联配置文档
   }


	//配置文档信息
   private  ApiInfo apiInfo(){

       //作者信息
       Contact DEFAULT_CONTACT = new Contact("作者", "作者链接", "作者邮箱");

       return new ApiInfo(
               "PenEn's API Documentation", // 标题
               "无论遇到什么困难，都要坚信自己前途无量", // 描述
               "1.0", // 版本号
               "https://www.baidu.com/", // 链接
               DEFAULT_CONTACT, // 作者
               "Apache 2.0",  // apache许可
               "http://www.apache.org/licenses/LICENSE-2.0", // 许可链接
               new ArrayList()); // 扩展
   }

}

创建Swagger实例Docket时 可以通过 ApiInfo配置文档信息

通过链式编程关联ApiInfo
return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo());

重启项目查看效果

配置扫描接口

Docket通过 .select() 方法来扫描接口
					.apis() 扫描哪个接口
					.path()  过滤扫描的接口(不扫描)
					.buid() 构造

// 配置Swagger的Docket实例
@Bean
public Docket docket(){

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select() // 配置扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
            .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
            .build();
}

apis(RequestHandlerSelectors.basePackage(“com.it.controller”))
表示扫描com.it.controller 下的接口

.paths(PathSelectors.ant(“con.it/*”))
表示过滤扫描 cont.it./*下的接口

apis（）方法中的参数可以是↓

	any() : 扫描所有，项目中所有接口都会被扫描
	none() : 不扫描接口
	withMethodAnnotation(final Class<? extends Annotation> annotation)
		通过 方法上  注解来扫描
	withClassAnnotation(final Class<? extends Annotation> annotation)
		通过  类上  注解来扫描
	basePackage(final String basePackage) : 根据包路径扫描接口


path（）方法中的参数可以是↓

	any()  : 任何请求都扫描
	none() :  任何请求都不扫描
	regex(final String pathRegex) :  通过正则表达式控制
	ant(final String antPattern) :  通过路径来过滤

配置Swagger开关

通过Docket实例 .enable() 方法配置开启或关闭Swagger
配置关闭后 Swagger不能在浏览器中访问

// 配置Swagger的Docket实例
@Bean
public Docket docket(){
   return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .enable(false) 
           .select() // 配置扫描接口
           .apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
           // .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
           .build();
}

enable（参数） 参数为true表示开启Swagger 可以在浏览器中访问
		      参数为false 表示关闭Swagger，不可以在浏览器中访问

我们可以动态配置开启或关闭Swagger

例如我们现在的项目处于 dev 环境 就开启Swagger 处于 pro 环境就关闭Swagger

我们在Resource下添加application-dev.properties 和 application-pro.properties 两个环境

实现方法

// 配置Swagger的Docket实例
@Bean
public Docket docket(Environment environment){ // 需要Environment参数

	// 设置要显示Swagger的环境
   Profiles profiles = Profiles.of("dev");
	
	// 判断当前是否处于该环境
   boolean flag = environment.acceptsProfiles(profiles);

   return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .enable(flag) //接收flag值来判断是否显示
           .select() // 配置扫描接口
           .apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
           // .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
           .build();
}

我们在 application.properties 中配置多环境Profile为 dev

# 设置环境为dev环境
spring.profiles.active=dev

测试发现如果配置了多环境切换为dev 则正常显示Swagger Api页面
如果没有配置就会显示
在这里插入图片描述

配置Swagger API 分组

通过Droket实例.groupName() 来配置分组
默认为default

// 配置Swagger的Docket实例
@Bean
public Docket docket(Environment environment){ // 需要Environment参数

	// 设置要显示Swagger的环境
   Profiles profiles = Profiles.of("dev");
	
	// 判断当前是否处于该环境
   boolean flag = environment.acceptsProfiles(profiles);

   return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .groupName("佩恩") // 分组名字为 佩恩
           .enable(flag) //接收flag值来判断是否显示
           .select() // 配置扫描接口
           .apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
           // .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
           .build();
}

可以重启项目访问swagger页面查看效果

如何配置多个分组

配置多个分组 我们只需要在Spring容器中多添加几个Docket实例就好了

@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {


  @Bean
  public Docket docket1(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("A");
  }

  @Bean
  public Docket docket2(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("B");
  }

  @Bean
  public Docket docket3(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("C");
  }



  // 配置Swagger的Docket实例
  @Bean
  public Docket docket(Environment environment){

      Profiles profiles = Profiles.of("dev");

      boolean flag = environment.acceptsProfiles(profiles);

      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .groupName("佩恩")
              .enable(flag)
              .select() // 配置扫描接口
              .apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
              // .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
              .build();
  }

重启项目查看效果

实体配置

1. 新建实体类

@ApiModel("用户实体类")
public class User {
   @ApiModelProperty("用户名")
   private String name;
   @ApiModelProperty("密码")
   private String password;

   public String getName() {
       return name;
   }

   public void setName(String name) {
       this.name = name;
   }

   public String getPassword() {
       return password;
   }

   public void setPassword(String password) {
       this.password = password;
   }
}

如果想让SwaggerAPI页面识别到这个bean 也就是在页面的Model下能看到，我们只需要将这个User 通过Controller 返回出去就OK

@GetMapping("/user")
@ResponseBody
public User user(){
	return new User();
}

重启后访问页面发现
在这里插入图片描述
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

@Api(tags = "xxx模块说明")	作用在模块类上

@ApiOperation("xxx接口说明")	作用在接口方法上

@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO

@ApiModelProperty(value = "xxx属性说明",hidden = true)	
作用在类方法和属性上，hidden设置为true可以隐藏该属性

@ApiParam("xxx参数说明")	作用在参数、方法和字段上，
类似@ApiModelProperty

我们可以在Controller中配置一些注释

 @PostMapping("/user1")
 @ResponseBody
 @ApiOperation("测试返回User")
 public User user1(@ApiParam("User实体类") User user){
     return user;
 }

六道佩奇。

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
1
评论
SpringBoot-Swagger集成

初识Swagger1. 环境搭建创建SpringBoot-web项目1. 导入依赖<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> &
复制链接

扫一扫