SpringBoot-20-集成Swagger

最新推荐文章于 2025-03-11 18:39:43 发布

paiidds

最新推荐文章于 2025-03-11 18:39:43 发布

阅读量485

点赞数

文章标签： spring boot spring

本文链接：https://blog.youkuaiyun.com/paiidds/article/details/124073228

版权

Swagger简介

1.Swagger是什么?

	    Swagger是一框优秀的前后端分离API框架，能提高我们的开发效率，用于生成、描述、调用、可视化Restful

风格的Web服务。

		Swagger衍生出的一系列项目和工具，可以做到生成各种格式的接口文档，生成多种语言的的客户端和服务器

端代码，更新Swagger描述文件，就可以自动生成接口文档，服务端代码，做到调用端代码，服务器代码，接口文档的

一致性.

2.Swagger的产生背景

		前后端集成，前端和后端无法做到"及时协商，尽早解决"，最终导致问题集中爆发。

3.Swagger的解决方案

		首先定义schema【计划的提纲】，并实时跟踪最新的API，降低集成风险。

4.Swagger优点

流行的API(应用程序接口)框架，开发人员直接调用封装好的框架，来提高开发效率
Restful Api 文档在线自动生成器 =>API文档和API定义同步更新，节省文档编写时间
直接运行，提供在线测试API
支持多种语言(如: Java,PHP)
官网:https://swagger.io/

在这里插入图片描述

SpringBoot集成Swagger

1.准备工作

版本问题: 使用jdk1.8版本及以上，否则swagger无法运行
添加jar包: 1. Springfox-swagger2 2.swaager-springmvc

Spring整合Swagger,只需要在项目中引入Springfox，扫描相关的代码，生成Swagger描述文件

2.代码实现

新建一个SpringBoot-11-Swagger项目
添加Maven依赖

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

测试是否能运行成功
在com.liang.controller包下,创建一个HelloController进行测试

@Controller
@RequestMapping("/hello")
public class HelloController {

    @GetMapping ("/s")
    @ResponseBody
    public String  sayHello(){
        return "hello";
    }
 }

使用Swagger
在com.liang.config包下,创建一个SwaggerConfig

@Configuration      //标记配置类
@EnableSwagger2    //开启Swagger2的自动配置，同时需要开启,否则Swagger2将会和Spring Boot默认的自动配置起冲突
@EnableWebMvc  //全面接管SpringMVC，SpringBoot的自动配置都失效，我们自己来配置
public class SwaggerConfig implements WebMvcConfigurer{  
}

启动SpringBoot ,输入localhost:8080/swagger-ui.html
在这里插入图片描述

配置Swagger信息
Swagger的实例Bean是一个Docket类，所以我们只需要向容器添加一个Docket的Bean就好了

@Bean 
public Docket docket() {
	//接口文档的类型为Swagger2
   return new Docket(DocumentationType.SWAGGER_2);
}

通过api.Info来配置文档基本信息
可以点开apiInfo来查看要填写哪些信息
在这里插入图片描述

自己写一个ApiInfo的方法


 public ApiInfo apiInfo()
    {
        //配置文档信息,使用Swagger的Contact类，使用的是springfox.documentation.service.Contact
        Contact contact = new Contact("联系人姓名","http://xxx.xxx.com/联系人访问连接","联系人邮箱");
        return new ApiInfo(
                "Swagger学习",     //标题
                "学习演示如何配置Swagger",  //描述
                "v1.0",         //版本
                "htttp://term.service.url/组织链接", //组织链接
                contact,            //；联系人信息
                "Apach 2.0 许可",  //许可
                "许可链接",      //许可链接
                 new ArrayList<>()       //拓展
        );
    }

然后再Docket实例关联上apiInfo()

  @Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

查看一下效果
在这里插入图片描述

配置扫描接口
通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口，配置完接口要调用build()方法创建ApiSelector对象

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.liang.controller"))//apis添加过滤条件
      .build();
}

测试项目，我们发现接口方法那块只有指定包路径下的接口方法

在这里插入图片描述
除了通过包路径下扫描接口外，还可以通过配置其他方式扫描接口

扫描接口的配置方式如下

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

配置接口扫描过滤

通过PathSelectors来配置接口过滤方式,它包含的方法有以下

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

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.liang.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/hello/**"))
      .build();
}

测试结果
在这里插入图片描述

配置Swagger开关
通过eable()方法来配置是否启用swagger的可视图UI界面，如果是false,则swagger不能在浏览器中访问，默认为true

        //构造函数初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
           //apiInfo: 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含
        //基本描述信息，开发中一般自定义
                .apiInfo(apiInfo())    //配置基本API信息
                .enable(true)         //配置是否启用Swagger,如果为false,无法再浏览器上访问,默认为true
                .select()              //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.liang.controller"))      //apis添加过滤条件
                .paths(PathSelectors.ant("/hello/**"))      //配置如何通过path过滤，这里只扫描请求以/hello开头的接口
//                // PathSelectors类中有多个path过滤方法, ant通过ant（）控制，any扫描任何请求，none不扫描任何请求,regex通过正则表达式控制
                .build();
    }

动态根据项目所处环境来确定是否显示Swagger

多环境配置


# 生产者配置环境
server:
  port: 8081


spring:
  #激活生产者模块
  #声明生产者环境模块
  config:
    activate:
      on-profile: dev

---  #开发者环境模块

server:
  port: 8082

spring:
  config:
    activate:
      on-profile: prod


--- #测试环境模块

server:
  port: 8083


spring:
  config:
    activate:
      on-profile: test

然后在application.properties写上配置的环境如下

	spring.profiles.active=prod

在Docket中的配置

    @Bean //配置docket以配置Swagger具体参数 docket的中文意思是记事表
    public Docket docket(Environment environment)
    {
        //设置要显示swagger的环境
        Profiles of  = Profiles.of("dev","test");
        //判断当前环境是否处于该环境
        boolean b = environment.acceptsProfiles(of);

        //构造函数初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
           //apiInfo: 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含
        //基本描述信息，开发中一般自定义
                .apiInfo(apiInfo())    //配置基本API信息
                .enable(b)         //配置是否启用Swagger,如果为false,无法再浏览器上访问,默认为true
                .select()              //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.liang.controller"))      //apis添加过滤条件
                .paths(PathSelectors.ant("/hello/**"))      //配置如何通过path过滤，这里只扫描请求以/hello开头的接口
//                // PathSelectors类中有多个path过滤方法, ant通过ant（）控制，any扫描任何请求，none不扫描任何请求,regex通过正则表达式控制
                .build();
    }

配置API分组
使用groupName()的方法来配置Api分组

单个Api分组配置如下

    @Bean //配置docket以配置Swagger具体参数 docket的中文意思是记事表
    public Docket docket(Environment environment)
    {
        //设置要显示swagger的环境
        Profiles of  = Profiles.of("dev","test");
        //判断当前环境是否处于该环境
        boolean b = environment.acceptsProfiles(of);

        //构造函数初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
           //apiInfo: 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含
        //了基本描述信息，开发中一般自定义
                .apiInfo(apiInfo())    //配置基本API信息
                .groupName("hello")    //配置分组
                .enable(b)         //配置是否启用Swagger,如果为false,无法再浏览器上访问,默认为true
                .select()              //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.liang.controller"))      //apis添加过滤条件
                .paths(PathSelectors.ant("/hello/**"))      //配置如何通过path过滤，这里只扫描请求以/hello开头的接口
//                // PathSelectors类中有多个path过滤方法, ant通过ant（）控制，any扫描任何请求，none不扫描任何请求,regex通过正则表达式控制
                .build();
    }

配置多个Api分组

配置多个Docket实例

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");

测试查看即可
9. 实体配置

新疆一个实体类，使用到@ApiModel,@ApiModelProperty注解

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")  //可以设置hidden设置为true可以隐藏该属性
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

只要这个实体在请求接口的返回值上(即使是泛型)。都能映射到实体项中

    //Api实体列表 使用@ApiModel等注解
    @GetMapping("/user")
    public User getUser(){
        return new User();
    }

测试结果

在这里插入图片描述

@ApiModel和@ApiModelProperty是为实体类添加注释的

10 给请求接口配置注释

    //使用@Api请求列表 @ApiOperation @ApiParam能搞好的提高阅读性
    @ApiOperation("Liang的接口")           //作用在接口方法
    @PostMapping("/liang")
    @ResponseBody
    public String liang(@ApiParam("张三")String username)
    {
        return username;
    }

@ApiOperation作用在接口方法上
@ApiParam作用在参数、方法和字段上

测试结果

在这里插入图片描述

常用的注解

Swagger所有的注解定义在io.swagger.annotations包上
下面举例一些常用的

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

Swagger给我们难理解的属性或者接口添加了配置信息，让人更容易阅读

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

3.拓展

可以实现不同的皮肤定义，引入相应的Jar

到资源处理器中添加相应的视图跳转即可

    //添加资源处理器
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //配置资源处理器
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("docs.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("document.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        WebMvcConfigurer.super.addResourceHandlers(registry);
    }

1.默认的访问 http://localhost:8080/swagger-ui.html

之前使用的就是

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

在这里插入图片描述

3.Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

在这里插入图片描述

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>