SpringBoot 整合Swagger2

news2024/11/24 17:01:11

一、Swagger简介

Swagger是一套开源工具和规范，用于设计、构建和文档化RESTful Web服务。它允许开发人员定义API的各个方面，并生成易于理解的API文档和交互式API探索界面。同时，Swagger还提供代码生成工具，可自动生成与API交互的客户端和服务器端代码，提高开发效率。

  • 官网：https://swagger.io/

二、SpringBoot集成Swagger

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

  1. 新建一个SpringBoot-web项目

  2. 添加Maven依赖

    <dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

  3. 编写HelloController，测试确保运行成功！

    @RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello swagger";
    }
}

  4. 要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swagger

     package com.liming.config;
 
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
 @Configuration
 @EnableSwagger2// 开启Swagger2的自动配置
 public class SwaggerConfig extends WebMvcConfigurationSupport {
 
     /**
      * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
      * @param registry void
      */
     @Override
     protected void addResourceHandlers(ResourceHandlerRegistry registry) {
         // 解决静态资源无法访问
         registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
         // 解决swagger无法访问
         registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
         // 解决swagger的js文件无法访问
         registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
     }
 }

  5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

    在这里插入图片描述

三、配置Swagger

  1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

    @Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

  2. 可以通过apiInfo()属性配置文档信息

     //配置文档信息
 private ApiInfo apiInfo() {
     return new ApiInfoBuilder()
             .title("Swagger标题") // 标题
             .description("学习演示如何配置Swagger") //描述
             .version("v1.0") // 版本
             .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
             .build();
 }

  3. Docket 实例关联上 apiInfo()

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

  4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

    在这里插入图片描述

四、配置扫描接口

  1. 构建Docket时通过select()方法配置怎么扫描接口。

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

  2. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

    在这里插入图片描述

  3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

    1、basePackage(final String basePackage) // 根据包路径扫描接口
    2、any() // 扫描所有，项目中的所有接口都会被扫描到
    3、none() // 不扫描接口

    4、// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
    withMethodAnnotation(final Class<? extends Annotation> annotation)
    5、// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    withClassAnnotation(final Class<? extends Annotation> annotation)

  4. 除此之外，我们还可以配置接口扫描过滤：

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

  5. 这里的可选值还有

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

SwaggerConfig基础配置全代码

package com.liming.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.limjing.controller")) // 只扫描controller接口
                .paths(PathSelectors.any()) // 配置如何通过path过滤,即这里扫描所有请求的接口
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
                .build();
    }

    /**
     * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
     *
     * @param registry void
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

五、配置Swagger开关

  1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

    @Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()
      .apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller"))
      .paths(PathSelectors.ant("/ss/**"))
      .build();
}

    在这里插入图片描述

  2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

    @Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean flag = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(flag)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
      .paths(PathSelectors.ant("/user/**"))
      .build();
}

  3. 可以在项目中增加配置文件

    application.yml ->spring.profiles.active=dev
    application-dev.yml ->端口：8081
    application-pro.yml->端口：8082

    结果：pro正式环境会关闭swagger功能

六、配置API分组

  1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

    @Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("黎明") // 配置分组
       // 省略配置....
}

  2. 重启项目查看分组

    在这里插入图片描述

  3. 如何配置多个分组？配置多个分组只需要配置多个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");
}

  4. 重启项目查看即可

    在这里插入图片描述

七、实体配置

  1. 新建一个实体类

    //@Api("注释")
@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

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

  2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

    @RestController
public class HelloController {

    //   /error默认错误请求
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }
}

  3. 重启查看测试

    image-20200731200413725

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的.

  • @ApiModel为类添加注释

  • @ApiModelProperty为类属性添加注释

【注意点】：在正式发布的时候，关闭Swagger！！！

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

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

我们也可以给请求的接口配置一些注释

  1. 在HelloController控制类中的接口添加api接口注释

    @RestController
public class HelloController {
    ......
    @ApiOperation("Hello控制接口")
    @GetMapping("/hello")
    public String hello2(@ApiParam("用户名") String username) {
        return "hello" + username;
    }
    
    @ApiOperation("get测试")
    @GetMapping("/get")
    public User hello2(@ApiParam("用户") User user) {
        return user;
    }
}

    image-20200731201755001

  2. 进行try it out测试

    image-20200731202958255

    测试结果

    image-20200731203034702

拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

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

<dependency> 
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

在这里插入图片描述

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

<!--swaggerconfig解决高版本那里要换成doc.html-->
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

image-20200731205550845

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/865819.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

公文撰写规范：提升文档质量和专业性

公文撰写规范：提升文档质量和专业性

1.拼写和语法检查&#xff1a;仔细检查文档中的拼写错误和语法错误。确保单词的正确拼写&#xff0c;并使用正确的语法结构和标点符号。 2.信息准确性&#xff1a;核对文档中的事实和数据&#xff0c;确保其准确性。确认所有日期、数字和引用的信息是否准确无误。 3.文档结构和…
阅读更多...
控制国外各类电液伺服阀放大器

控制国外各类电液伺服阀放大器

控制通用型不带反馈信号输入的伺服阀放大器&#xff0c;对射流管式电液伺服阀、喷嘴挡板式电液伺服阀及国外各类电液伺服阀进行控制。 通过系统参数有10V和4~20mA输入指令信号选择&#xff1b; 供电电源: 24VDC&#xff08;标准&#xff09; 输出电流&#xff1a;最大可达10…
阅读更多...
Kuebernetes资源控制管理

Kuebernetes资源控制管理

第四阶段 时 间&#xff1a;2023年8月11日 参加人&#xff1a;全班人员 内 容&#xff1a; Kuebernetes资源控制管理 目录 Kubectl命令工具 一、kubectl 命令行的语法 二、kubectl命令列表 三、使用 Kubectl 工具容器资源 &#xff08;一&#xff09;创建Pod &…
阅读更多...
并发——ThreadLocal关键字详解

并发——ThreadLocal关键字详解

文章目录 前言ThreadLocal代码演示ThreadLocal的数据结构GC 之后key是否为null&#xff1f;ThreadLocal.set()方法源码详解ThreadLocalMap Hash算法ThreadLocalMap Hash冲突ThreadLocalMap.set()详解ThreadLocalMap.set()原理图解ThreadLocalMap.set()源码详解 ThreadLocalMap过…
阅读更多...
游戏选香港主机会很卡吗？

游戏选香港主机会很卡吗？

​　　经常会有用户问道&#xff1a;做游戏服务器&#xff0c;使用香港主机会很卡吗?要知道&#xff0c;游戏运营最看重的就是用户体验&#xff0c;而游戏流畅不流畅要看所使用香港服务器本身的稳定性。因此&#xff0c;卡不卡&#xff0c;这样的形式提问是比较笼统的&#xf…
阅读更多...
【EI检索】第九届建筑、土木与水利工程国际学术会议（ICACHE 2023）

【EI检索】第九届建筑、土木与水利工程国际学术会议（ICACHE 2023）

第九届建筑、土木与水利工程国际学术会议&#xff08;ICACHE 2023&#xff09; 2023 9th International Conference on Architectural, Civil and Hydraulic Engineering 第九届建筑、土木与水利工程国际学术会议&#xff08;ICACHE 2023&#xff09;将于2023年10月13-15日在中…
阅读更多...
现代无人机技术

现代无人机技术

目录 1.发展 2.应用领域 3.对战争的影响 4.给人类带来的福利 5.给人类带来的坏处 1.发展 无人机的发展可以分为以下几个关键步骤&#xff1a; 1. 早期试验和研究&#xff1a;20世纪初&#xff0c;飞行器的概念开始出现&#xff0c;并进行了一些早期的试飞和实验。这些尝试包…
阅读更多...
第一部分：核心容器

第一部分：核心容器

前言&#xff1a;学习路线 Spring就是一个轻量级的控制反转&#xff08;IOC&#xff09;和面向切面编程&#xff08;AOP&#xff09;的框架&#xff01; 第一章&#xff1a;纯手写 一、核心概念 什么是IoC、IoC容器、bean、DI &#xff1f; IoC&#xff1a;对象创建控制权由程…
阅读更多...
springboot项目为什么加载不出来页面

springboot项目为什么加载不出来页面

路径啥的都没问题。hh&#xff0c;非常简单&#xff0c;因为springboot项目默认访问静态static文件&#xff0c;把那种静态图片放在static文件下就解决了。
阅读更多...
订单支付超时未支付关闭订单的解决方案

订单支付超时未支付关闭订单的解决方案

订单支付超时未支付关闭订单的解决方案 假设有客户下了订单但是迟迟未曾支付&#xff0c;会产生什么样的问题呢&#xff0c;大家联想一下京东淘宝拼多多&#xff0c;想一下大家购物的场景中&#xff0c;人家是怎么做的&#xff0c;然后再看看我们这么这篇文章&#xff01;&…
阅读更多...
微信怎么恢复好友？这8个方法值得一试！

微信怎么恢复好友？这8个方法值得一试！

【微信之前忘记给别人备注名字&#xff0c;昨天清理好友时不小心误删了该怎么办啊&#xff01;好尴尬&#xff01;】 随着社交网络的快速发展&#xff0c;微信已成为我们生活中必不可少的交流工具。日积月累下来&#xff0c;微信里的联系人也就变得越来越多。但是&#xff0c;…
阅读更多...
Map映射学习

Map映射学习

一、Map的遍历 创建Map集合 Map<String, Integer> map new HashMap<>();添加元素 map.put("java", 99);map.put("c", 88);map.put("c", 93);map.put("python", 96);map.put("Go", 88); 遍历方法&#xff1a; …
阅读更多...
自主学习库简化智能代理创建

自主学习库简化智能代理创建

观看当今毁灭人类的智能代理玩复杂的视频游戏可能很有趣 - 但创建一个是另一回事。构建有效的智能代理需要设置大量超参数来塑造环境、建立奖励等。来自马萨诸塞大学阿默斯特分校的一组研究人员试图通过他们新的自主学习图书馆项目来简化这一过程。 自治学习库是 PyTorch 的深…
阅读更多...
Mysql - 配置Mysql主从复制-keepalived高可用-读写分离集群

Mysql - 配置Mysql主从复制-keepalived高可用-读写分离集群

目录 高可用&#xff1a; 为什么需要高可用呢&#xff1f; 高可用的主要作用&#xff1a; keepalived是什么&#xff1f;它用在哪里&#xff1f; 什么是VRRP协议&#xff0c;它的作用是什么&#xff1f; 搭建一个基于keepalived的高可用Mysql主从复制读写分离集群 一、项…
阅读更多...
【vue3】解决scope.row.id套标签太多无法随着点击按钮而变化

【vue3】解决scope.row.id套标签太多无法随着点击按钮而变化

实现要求:再点击每一行的修改按钮时&#xff0c;动态拿取该行的id传给后端作为pk(主键)实现数据库数据的修改&#xff0c;并显示在vue前端&#xff1b; 我遇到的问题&#xff1a;在2处使用 scope 作用域插槽拿取每一行的数据&#xff0c;在3处&#xff0c;删除按钮那一行代码&a…
阅读更多...
BGP小综合

BGP小综合

实验要求及拓扑 一、思路 1.使用OSPF使R2-R7之间可通。 2.各自宣告AS区域&#xff0c;两个区域两两之间建邻&#xff0c;AS2两个小区域之间建联邦&#xff08;R2与R5、R4与R7&#xff09;。 3.使R3、R6为路由反射器 RR反射器选取各小区域的路由器作为客户端 、非客户端 4.优…
阅读更多...
分布式事务模式理论详解

分布式事务模式理论详解

&#x1f680; 分布式事务 &#x1f680; &#x1f332; AI工具、AI绘图、AI专栏 &#x1f340; &#x1f332; 如果你想学到最前沿、最火爆的技术&#xff0c;赶快加入吧✨ &#x1f332; 作者简介&#xff1a;硕风和炜&#xff0c;CSDN-Java领域优质创作者&#x1f3c6;&…
阅读更多...
SaaS，PaaS，IaaS之间的主要区别

SaaS，PaaS，IaaS之间的主要区别

SaaS&#xff0c;PaaS&#xff0c;IaaS之间的主要区别 不久之前&#xff0c;公司的所有IT系统都是本地部署&#xff0c;而云也只是天空中蓬松的白色物体。现在&#xff0c;几乎所有系统和进程都可以使用云平台。SaaS&#xff0c;PaaS和IaaS只是描述如何在企业中使用云的三种方…
阅读更多...
DL_20无线串口模块

DL_20无线串口模块

今日介绍一块最近入手的无线串口模块&#xff0c;40r左右&#xff0c;精简好用&#xff0c;虽然感觉配置波特率啥的并不智能化&#xff0c;但250米的通信距离还是很顶的&#xff01;它的升级版甚至有1000米的通信距离&#xff08;空旷地带&#xff09; 这篇文章不多讲其余话&am…
阅读更多...
（二）结构型模式：1、适配器模式（Adapter Pattern）（C++实现示例）

（二）结构型模式：1、适配器模式（Adapter Pattern）（C++实现示例）

目录 1、适配器模式&#xff08;Adapter Pattern&#xff09;含义 2、适配器模式应用场景 3、适配器模式的UML图学习 4、C实现适配器模式的示例 1、适配器模式&#xff08;Adapter Pattern&#xff09;含义 将一个接口转换为客户端所期待的接口&#xff0c;从而使两个接口…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023